diff --git a/.claude/commands/cx-spec.analyze.md b/.claude/commands/cx-spec.analyze.md new file mode 100644 index 000000000..9f0c8a06a --- /dev/null +++ b/.claude/commands/cx-spec.analyze.md @@ -0,0 +1,446 @@ +--- +description: Check consistency across spec, plan, and tasks +--- + +## User Input + +```text +$ARGUMENTS +``` + + +You **MUST** consider the user input before proceeding (if not empty). + +## Shell Compatibility + +- Use `.cx-spec/scripts/bash/...` on macOS/Linux. +- Use `.cx-spec/scripts/powershell/...` on Windows. +- If a step shows only one shell form, use the equivalent script in the other shell. + + + + + +## Goal + +Perform consistency and quality analysis across artifacts and implementation with automatic context detection: + +**Auto-Detection Logic**: + +- **Pre-Implementation**: When spec.md exists but no implementation artifacts detected (tasks.md required in spec mode, optional in build mode) +- **Post-Implementation**: When implementation artifacts exist (source code, build outputs, etc.) + +**Pre-Implementation Analysis**: Identify inconsistencies, duplications, ambiguities, and underspecified items across available artifacts (`spec.md` required, `plan.md` and `tasks.md` optional in build mode, all required in spec mode) before implementation. In spec mode, this command should run after `/cx-spec.tasks` has successfully produced a complete `tasks.md`. + +**Post-Implementation Analysis**: Analyze actual implemented code against documentation to identify refinement opportunities, synchronization needs, and real-world improvements. + +**Architecture Cross-Validation** (NEW): When architecture artifacts exist (`.cx-spec/memory/architecture.md` or `specs/{feature}/architecture.md`), validate spec and plan alignment with system and feature-level architecture constraints. + +This command adapts its behavior based on project state and workflow mode. + +## Operating Constraints + +**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually). + +**Auto-Detection Logic**: + +1. Auto-detect workflow mode and framework options from spec.md using `detect_workflow_config()` +2. Analyze project state: + - **Pre-implementation**: + - **Build mode**: spec.md exists, no implementation artifacts (plan.md/tasks.md optional) + - **Spec mode**: tasks.md exists, no source code or build artifacts + - **Post-implementation**: Source code directories, compiled outputs, or deployment artifacts exist +3. Apply mode-aware analysis depth: + - **Build mode**: Lightweight analysis appropriate for rapid iteration + - **Spec mode**: Comprehensive analysis with full validation + +**Constitution Authority**: The project constitution (`.cx-spec/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/cx-spec.analyze`. + +## Execution Steps + +### 1. Initialize Analysis Context + +Run `.cx-spec/scripts/bash/check-prerequisites.sh --json --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths: + +- SPEC = FEATURE_DIR/spec.md +- PLAN = FEATURE_DIR/plan.md +- TASKS = FEATURE_DIR/tasks.md + +For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +### 2. Auto-Detect Analysis Mode + +**Context Analysis**: + +1. **Auto-Detect from Spec**: Use `detect_workflow_config()` to read mode and framework options from spec.md metadata +2. **Analyze Project State**: + - Scan for implementation artifacts (src/, build/, dist/, *.js,*.py, etc.) + - Check git history for implementation commits + - Verify if `/implement` has been run recently +3. **Determine Analysis Type**: + - **Pre-Implementation**: + - **Build mode**: spec.md exists, no implementation artifacts (plan.md/tasks.md optional) + - **Spec mode**: spec.md + tasks.md exist, no implementation artifacts (plan.md recommended) + - **Post-Implementation**: Implementation artifacts exist +4. **Apply Mode-Aware Depth**: + - **Build Mode**: Focus on core functionality and quick iterations + - **Spec Mode**: Comprehensive analysis with full validation + +**Fallback Logic**: If detection is ambiguous, default to pre-implementation analysis appropriate for the current mode and prompt user for clarification. + +### 3. Load Artifacts (Auto-Detected Mode) + +**Pre-Implementation Mode Artifacts:** +Load available artifacts (build mode may have only spec.md): + +**From spec.md (required):** + +- Overview/Context +- Functional Requirements +- Non-Functional Requirements +- User Stories +- Edge Cases (if present) + +**From plan.md (optional in build mode):** + +- Architecture/stack choices +- Data Model references +- Phases +- Technical constraints + +**From tasks.md (optional in build mode):** + +- Task IDs +- Descriptions +- Phase grouping +- Parallel markers [P] +- Referenced file paths + +**Post-Implementation Mode Artifacts:** +Load documentation artifacts plus analyze actual codebase: + +**From Documentation:** + +- All artifacts as above (if available) +- Implementation notes and decisions + +**From Codebase:** + +- Scan source code for implemented functionality +- Check for undocumented features or changes +- Analyze performance patterns and architecture usage +- Identify manual modifications not reflected in documentation + +**From constitution:** + +- Load `.cx-spec/memory/constitution.md` for principle validation (both modes) + +**From architecture (if exists):** + +- Load `.cx-spec/memory/architecture.md` for system-level architecture context (includes ADRs in Section 6) +- Load `specs/{feature}/architecture.md` for feature-level architecture (if `--architecture` was enabled) + +### 3. Build Semantic Models + +Create internal representations (do not include raw artifacts in output): + +- **Requirements inventory**: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" → `user-can-upload-file`) +- **User story/action inventory**: Discrete user actions with acceptance criteria +- **Task coverage mapping**: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases) +- **Constitution rule set**: Extract principle names and MUST/SHOULD normative statements + +### 4. Detection Passes (Auto-Detected Analysis) + +Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary. + +**BRANCH BY AUTO-DETECTED MODE:** + +#### Pre-Implementation Detection Passes + +#### A. Duplication Detection + +- Identify near-duplicate requirements +- Mark lower-quality phrasing for consolidation + +#### B. Ambiguity Detection + +- Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria +- Flag unresolved placeholders (TODO, TKTK, ???, ``, etc.) + +#### C. Underspecification + +- Requirements with verbs but missing object or measurable outcome +- User stories missing acceptance criteria alignment +- Tasks referencing files or components not defined in spec/plan (if tasks.md exists) + +#### D. Constitution Alignment + +- Any requirement or plan element conflicting with a MUST principle +- Missing mandated sections or quality gates from constitution + +#### E. Coverage Gaps + +- Requirements with zero associated tasks (if tasks.md exists) +- Tasks with no mapped requirement/story (if tasks.md exists) +- Non-functional requirements not reflected in tasks (if tasks.md exists) + +#### F. Inconsistency + +- Terminology drift (same concept named differently across files) +- Data entities referenced in plan but absent in spec (or vice versa) +- Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note) +- Conflicting requirements (e.g., one requires Next.js while other specifies Vue) + +#### Post-Implementation Detection Passes + +##### G. Documentation Drift + +- Implemented features not documented in spec.md +- Code architecture differing from plan.md +- Manual changes not reflected in documentation +- Deprecated code still referenced in docs + +##### H. Implementation Quality + +- Performance bottlenecks not anticipated in spec +- Security issues discovered during implementation +- Scalability problems with current architecture +- Code maintainability concerns + +##### I. Real-World Usage Gaps + +- User experience issues not covered in requirements +- Edge cases discovered during testing/usage +- Integration problems with external systems +- Data validation issues in production + +##### J. Refinement Opportunities + +- Code optimizations possible +- Architecture improvements identified +- Testing gaps revealed +- Monitoring/logging enhancements needed + +#### K. Smart Trace Validation (Both Modes) + +**Purpose**: Ensure spec-to-issue traceability is maintained throughout the SDD workflow using `@issue-tracker ISSUE-123` syntax. + +**Detection Logic**: + +1. **Scan all artifacts** for existing `@issue-tracker` references +2. **Extract issue IDs** from patterns like `@issue-tracker PROJ-123`, `@issue-tracker #456`, `@issue-tracker GITHUB-789` +3. **Validate coverage**: + - **Spec-level traces**: Every major feature/user story should have at least one issue reference + - **Task-level traces**: Implementation tasks should reference parent spec issues + - **Cross-artifact consistency**: Same issue IDs used across spec.md, plan.md, tasks.md +4. **Check MCP configuration**: Verify `.mcp.json` exists and issue tracker is properly configured + +**Traceability Gaps to Detect**: + +- **Missing spec traces**: User stories or major features without `@issue-tracker` references +- **Orphaned tasks**: Implementation tasks not linked to spec-level issues +- **Inconsistent issue references**: Same feature referenced with different issue IDs across artifacts +- **Invalid issue formats**: Malformed issue references that won't integrate with MCP +- **MCP misconfiguration**: Issue tracker not configured in `.mcp.json` + +**Validation Rules**: + +- **Minimum coverage**: ≥80% of user stories/requirements should have traceable issue links +- **Format validation**: Issue references must match configured tracker patterns (GitHub/Jira/Linear/GitLab) +- **Consistency check**: Issue IDs should be consistent across spec.md → plan.md → tasks.md +- **MCP readiness**: `.mcp.json` must exist and contain valid issue tracker configuration + +### 5. Severity Assignment (Mode-Aware) + +Use this heuristic to prioritize findings: + +**Pre-Implementation Severities:** + +- **CRITICAL**: Violates constitution MUST, missing spec.md, or requirement with zero coverage that blocks baseline functionality +- **HIGH**: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion +- **MEDIUM**: Terminology drift, missing non-functional task coverage, underspecified edge case, missing plan.md/tasks.md (build mode only) +- **LOW**: Style/wording improvements, minor redundancy not affecting execution order + +**Post-Implementation Severities:** + +- **CRITICAL**: Security vulnerabilities, data corruption risks, or system stability issues +- **HIGH**: Performance problems affecting user experience, undocumented breaking changes +- **MEDIUM**: Code quality issues, missing tests, documentation drift +- **LOW**: Optimization opportunities, minor improvements, style enhancements + +### 6. Produce Compact Analysis Report (Auto-Detected) + +Output a Markdown report (no file writes) with auto-detected mode-appropriate structure. Include detection summary at the top: + +#### Pre-Implementation Report Structure + +## Pre-Implementation Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version | + +**Coverage Summary Table:** + +| Requirement Key | Has Task? | Task IDs | Notes | +|-----------------|-----------|----------|-------| + +**Constitution Alignment Issues:** (if any) + +**Unmapped Tasks:** (if any) + +**Metrics:** + +- Total Requirements +- Total Tasks +- Coverage % (requirements with >=1 task) +- Ambiguity Count +- Duplication Count +- Critical Issues Count + +**Traceability Validation:** + +- **Issue Coverage**: X/Y user stories have @issue-tracker references (Z%) +- **MCP Status**: ✅ Configured (GitHub) / ❌ Missing .mcp.json +- **Format Validation**: All issue references use valid formats +- **Consistency Check**: Issue IDs consistent across artifacts + +### Post-Implementation Report Structure + +## Post-Implementation Analysis Report + +| ID | Category | Severity | Location(s) | Summary | Recommendation | +|----|----------|----------|-------------|---------|----------------| +| G1 | Documentation Drift | HIGH | src/auth.js | JWT implementation not in spec | Update spec.md to document JWT usage | + +**Implementation vs Documentation Gaps:** + +| Area | Implemented | Documented | Gap Analysis | +|------|-------------|------------|--------------| +| Authentication | JWT + OAuth2 | Basic auth only | Missing OAuth2 in spec | + +**Code Quality Metrics:** + +- Lines of code analyzed +- Test coverage percentage +- Performance bottlenecks identified +- Security issues found + +**Refinement Opportunities:** + +- Performance optimizations +- Architecture improvements +- Testing enhancements +- Documentation updates needed + +**Traceability Validation:** + +- **Issue Coverage**: X/Y user stories have @issue-tracker references (Z%) +- **MCP Status**: ✅ Configured (GitHub) / ❌ Missing .mcp.json +- **Format Validation**: All issue references use valid formats +- **Consistency Check**: Issue IDs consistent across artifacts + +### 7. Provide Next Actions (Auto-Detected) + +At end of report, output a concise Next Actions block based on detected mode and findings: + +**Pre-Implementation Next Actions:** + +- **Build Mode**: Missing plan.md/tasks.md is not critical - user may proceed to `/implement` for lightweight development +- **Spec Mode**: - If CRITICAL issues exist: Recommend resolving before `/cx-spec.implement` +- If only LOW/MEDIUM: User may proceed, but provide improvement suggestions +- Provide explicit command suggestions: e.g., "Run /cx-spec.specify with refinement", "Run /cx-spec.plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" +- **Traceability**: If <80% coverage: "Add @issue-tracker ISSUE-123 references to major user stories in spec.md" +- Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'" + +**Post-Implementation Next Actions:** + +- If CRITICAL issues exist: Recommend immediate fixes for security/stability +- If HIGH issues exist: Suggest prioritization for next iteration +- **Traceability**: If gaps found: "Update issue status in tracker and ensure all implemented features are linked via @issue-tracker references" +- Provide refinement suggestions: e.g., "Consider performance optimization", "Update documentation for new features", "Add missing test coverage" +- Suggest follow-up commands: e.g., "Run /plan to update architecture docs", "Run /specify to document new requirements" + +### 8. Offer Remediation + +Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.) + +### 9. Documentation Evolution (Post-Implementation Only) + +**When Post-Implementation Analysis Detects Significant Changes:** + +If the analysis reveals substantial implementation changes that should be reflected in documentation, offer to evolve the documentation: + +**Documentation Evolution Options:** + +- **Spec Updates**: Add newly discovered requirements, edge cases, or user experience insights +- **Plan Updates**: Document architecture changes, performance optimizations, or integration decisions +- **Task Updates**: Mark completed tasks, add follow-up tasks for refinements + +**Evolution Workflow:** + +1. **Identify Changes**: Flag implemented features not in spec.md, architecture deviations from plan.md +2. **Propose Updates**: Suggest specific additions to documentation artifacts +3. **Preserve Intent**: Ensure updates maintain original requirements while incorporating implementation learnings +4. **Version Tracking**: Create new versions of documentation with clear change rationale + +**Evolution Triggers:** + +- New features implemented but not specified +- Architecture changes for performance/security reasons +- User experience improvements discovered during implementation +- Integration requirements not anticipated in planning + +### 10. Rollback Integration + +**When Analysis Reveals Critical Issues:** + +If post-implementation analysis identifies critical problems requiring rollback: + +**Rollback Options:** + +- **Task-Level Rollback**: Revert individual tasks while preserving completed work +- **Feature Rollback**: Roll back entire feature implementation +- **Documentation Preservation**: Keep documentation updates even when code is rolled back + +**Rollback Workflow:** + +1. **Assess Impact**: Determine which tasks/code to rollback +2. **Preserve Documentation**: Keep spec/plan updates that reflect learnings +3. **Clean Revert**: Remove problematic implementation while maintaining good changes +4. **Regenerate Tasks**: Create new tasks for corrected implementation approach + +## Operating Principles + +### Context Efficiency + +- **Minimal high-signal tokens**: Focus on actionable findings, not exhaustive documentation +- **Progressive disclosure**: Load artifacts incrementally; don't dump all content into analysis +- **Token-efficient output**: Limit findings table to 50 rows; summarize overflow +- **Deterministic results**: Rerunning without changes should produce consistent IDs and counts + +### Analysis Guidelines + +- **NEVER modify files** (this is read-only analysis) +- **NEVER hallucinate missing sections** (if absent, report them accurately) +- **Prioritize constitution violations** (these are always CRITICAL) +- **Use examples over exhaustive rules** (cite specific instances, not generic patterns) +- **Report zero issues gracefully** (emit success report with coverage statistics) + +### Auto-Detection Guidelines + +- **Context awareness**: Analyze project state to determine appropriate analysis type +- **Mode integration**: Respect workflow mode (build vs spec) for analysis depth +- **Progressive enhancement**: Start with basic detection, allow user override if needed +- **Clear communication**: Always report which analysis mode was auto-selected + +### Post-Implementation Guidelines + +- **Code analysis scope**: Focus on high-level architecture and functionality, not line-by-line code review +- **Documentation synchronization**: Identify gaps between code and docs without assuming intent +- **Refinement focus**: Suggest improvements based on real implementation experience +- **Performance awareness**: Flag obvious bottlenecks but don't micro-optimize + +## Context + +$ARGUMENTS diff --git a/.claude/commands/cx-spec.architect.md b/.claude/commands/cx-spec.architect.md new file mode 100644 index 000000000..1d96cfcf7 --- /dev/null +++ b/.claude/commands/cx-spec.architect.md @@ -0,0 +1,468 @@ +--- +description: Generate or update architecture documentation +handoffs: + - label: Create Spec + agent: cx-spec.specify + prompt: Create specification for feature within this architecture + send: false + - label: Analyze Architecture + agent: cx-spec.analyze + prompt: Analyze architecture for consistency and completeness + send: true +--- + +## User Input + +```text +$ARGUMENTS +``` + + +You **MUST** consider the user input before proceeding (if not empty). + +## Shell Compatibility + +- Use `.cx-spec/scripts/bash/...` on macOS/Linux. +- Use `.cx-spec/scripts/powershell/...` on Windows. +- If a step shows only one shell form, use the equivalent script in the other shell. + + + + + +**Examples of User Input**: + +- `init "B2B SaaS platform for supply chain management"` +- `map "Django monolith with PostgreSQL, React frontend, AWS deployment"` +- `update "Migrated to microservices, added event sourcing and Kafka"` +- `review "Focus on security compliance and performance scalability"` + +When users provide context like this, use it to inform your architecture work. This context helps you understand system scope, constraints, and focus areas without needing to ask basic questions. + +## Command Actions + +The `/architect` command accepts one of the following actions as the first parameter: + +```bash +/architect [action] [description] +``` + +**Available Actions**: + +- `init`: Initialize new architecture from scratch (greenfield project) +- `map`: Scan existing codebase to reverse-engineer architecture (brownfield project) +- `update`: Update architecture based on recent code/spec changes +- `review`: Validate architecture against constitution and best practices + +**Action Descriptions**: + +- **init**: Creates `.cx-spec/memory/architecture.md` from template when no architecture exists +- **map**: Analyzes existing codebase and populates architecture with detected technologies and structure +- **update**: Synchronizes architecture with current implementation state and recent changes +- **review**: Validates architecture completeness, consistency, and constitution compliance + +The description after the action provides context for the architecture work (system scope, constraints, focus areas). + +## Outline + +The text the user typed after `/cx-spec.architect` in the triggering message **is** the architecture action (init/map/update/review) and context. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. + +### If No Arguments Provided + +When user runs `/cx-spec.architect` without specifying an action, **always show help first**: + +1. **Display Available Actions**: + ``` + 🏛️ **Architecture Command** + + Available actions: + • `init` - Create new architecture from scratch (greenfield project) + • `map` - Reverse-engineer architecture from existing codebase (brownfield) + • `update` - Sync architecture with recent code/spec changes + • `review` - Validate architecture against constitution + + Usage: /cx-spec.architect [description] + ``` + +2. **Auto-Detect and Recommend**: + - Check if `.cx-spec/memory/architecture.md` exists + - Check if codebase has source files (look for: `src/`, `lib/`, `app/`, `*.py`, `*.js`, `*.ts`, `*.java`, `*.cs`, `*.go`, `package.json`, `pom.xml`, `*.csproj`, `go.mod`, `Cargo.toml`, etc.) + - Show recommendation: + - If `architecture.md` exists → "**Recommended:** `update` (architecture already exists)" + - If no `architecture.md` but has source files → "**Recommended:** `map` (existing codebase detected)" + - If no `architecture.md` and no source files → "**Recommended:** `init` (new project detected)" + +3. **Ask for Confirmation**: + ``` + Would you like to proceed with ``? + Or specify a different action: init | map | update | review + ``` + +4. **Wait for User Response** before proceeding. + +### If Action Provided + +Given the user's input, do this: + +1. **Parse the Action**: Determine if user wants: + - `init` - Initialize new architecture from scratch (greenfield) + - `map` - Scan existing codebase (brownfield/reverse-engineering) + - `update` - Sync architecture with recent changes + - `review` - Validate architecture against constitution + +2. **Load Current State**: + - Check if `.cx-spec/memory/architecture.md` exists + - Load `.cx-spec/memory/constitution.md` for alignment validation + - Check for team directives if available + +3. **Execute Appropriate Phase**: Run Phases 0-5 based on action type + +4. **Generate or Update Architecture**: Write/update `.cx-spec/memory/architecture.md` + +5. **Produce Output**: Report generation results, ADRs created, and next steps + +**NOTE:** The script creates or updates the architecture file before execution. You are responsible for populating it with substantial content following the Rozanski & Woods structure. + +## Availability + +Architecture commands are available in all workflow modes (build and spec). They operate silently - no errors or warnings if architecture.md or related files are missing. Architecture documentation is optional and can be used whenever system-level design is beneficial. + +## Diagram Generation (Automatic) + +Architecture diagrams are automatically generated for all 7 viewpoints based on your configured diagram format: + +- **Mermaid** (default): Professional diagrams that render in GitHub/GitLab markdown +- **ASCII**: Plain text diagrams that work everywhere, including terminals + +**Diagram Format Configuration:** + +The diagram format is configured in repo config at `.cx-spec/config.json`: + +```json +{ + "architecture": { + "diagram_format": "mermaid" // or "ascii" + } +} +``` + +**To change the diagram format:** + +1. Edit `.cx-spec/config.json` +2. Change `diagram_format` to either `"mermaid"` or `"ascii"` +3. Run `/cx-spec.architect update` to regenerate diagrams + +**Diagram Types Generated:** + +| View | Mermaid Type | ASCII Alternative | +|------|--------------|-------------------| +| Context | Graph (system boundary) | Box diagram with entities | +| Functional | Component diagram | ASCII component boxes | +| Information | ER diagram | Table-like entity relationships | +| Concurrency | Sequence diagram | Timeline notation | +| Development | Dependency graph | Directory tree with arrows | +| Deployment | Infrastructure graph | Network diagram | +| Operational | Flowchart | Workflow steps | + +**Diagram Validation:** + +Mermaid diagrams are validated using lightweight syntax checking. If validation fails, the system automatically falls back to ASCII format for that specific diagram. + +**Example Mermaid Diagram (Context View):** + +```mermaid +graph TD + Users["👥 Users"] + System["🏢 System"] + Database["🗄️ Database"] + + Users -->|Requests| System + System -->|Queries| Database +``` + +**Example ASCII Diagram (Context View):** + +```text + ┌──────────────┐ + │ Users │ + └──────┬───────┘ + │ + ▼ +┌──────────────────┐ +│ System │ +└──────┬───────────┘ + │ + ▼ +┌──────────────────┐ +│ Database │ +└──────────────────┘ +``` + +## Goal + +Generate, update, or validate comprehensive Architecture Descriptions following the Rozanski & Woods "Software Systems Architecture" methodology. Transform AI from a simple coder into a System Architect capable of describing complex, production-ready systems with structural integrity. + +## Role & Context + +You are acting as a **System Architect** responsible for creating and maintaining the global architecture that governs all feature development. Your architecture description serves as: + +- **Strategic Context** for all `/cx-spec.specify` and `/cx-spec.plan` commands +- **Governance Framework** ensuring features align with system boundaries +- **Communication Tool** for stakeholders across technical and business domains +- **Decision Record** capturing architectural rationale and trade-offs + +### Architecture Hierarchy + +- Architecture operates at the **system level**, above individual features +- The `.cx-spec/memory/architecture.md` file provides **global context** inherited by all feature specs +- Features must **validate against** architectural boundaries and constraints +- Architecture can be **updated incrementally** as features reveal new requirements + +### Rozanski & Woods Methodology + +- **7 Core Viewpoints**: Context, Functional, Information, Concurrency, Development, Deployment, Operational +- **2 Perspectives**: Security, Performance & Scalability (cross-cutting quality concerns) +- Each viewpoint addresses **specific stakeholder concerns** +- Architecture must be **traceable** to stakeholder needs + +### Integration Points + +- `context.md` for features will include **architecture summary** +- `/cx-spec.plan` reads architecture for **Global Constraints** validation +- Architecture updates trigger **impact analysis** across existing features + +## Execution Steps + +### Parse Action from User Input + +The command supports four actions: + +| Action | Purpose | When to Use | +|--------|---------|-------------| +| `init` | Initialize new architecture from template | Greenfield projects, new systems | +| `map` | Scan existing codebase to populate architecture | Brownfield projects, reverse engineering | +| `update` | Update architecture based on code/spec changes | After feature implementation | +| `review` | Validate architecture against constitution | Before major milestones | + +**If no action specified**: Show help, auto-detect recommendation, and ask for confirmation (see "If No Arguments Provided" in Outline section above). + +### Phase 0: Context Discovery (for `init` and `map`) + +**Objective**: Establish stakeholders, concerns, and system scope + +**If user provided context in $ARGUMENTS**: Parse it for system description, scope, and constraints. Use this to skip basic questions and focus on clarifying details. + +**If user provided minimal/no context**: Follow full discovery process below. + +1. **Identify Stakeholders**: + - Read `.cx-spec/memory/constitution.md` if it exists + - Prompt user to identify key stakeholders (Product Owner, Operations, Security, End Users) + - Document their primary concerns + +2. **Define System Scope**: + - What problem does this system solve? + - What is explicitly IN scope? + - What is explicitly OUT of scope? + +3. **Load Team Directives**: + - Check for team-ai-directives in project + - Extract architectural principles and constraints + - Incorporate into Global Constraints section + +### Phase 1: Generate Architecture Views (for `init`) + +Generate each viewpoint systematically, starting with Context View (which informs the others): + +#### Order of Generation + +1. **Context View** (external boundaries) +2. **Functional View** (internal components) +3. **Information View** (data flow) +4. **Concurrency View** (runtime behavior) +5. **Development View** (code organization) +6. **Deployment View** (infrastructure) +7. **Operational View** (operations) + +**For each viewpoint**: + +- Use the template structure from `{REPO_ROOT}/.cx-spec/templates/architecture-template.md` +- Fill in specific details based on user input or codebase analysis +- Use tables for structured data, diagrams for relationships +- Keep descriptions concise but complete + +### Phase 2: Brownfield Mapping (for `map` action) + +**Objective**: Reverse-engineer architecture from existing codebase + +The script will scan the codebase and output structured findings. Use these to populate: + +1. **Development View**: + - Directory structure → Code Organization + - Package files → Module Dependencies + - CI/CD configs → Build & CI/CD + +2. **Deployment View**: + - `docker-compose.yml`, `Dockerfile` → Runtime Environments + - Kubernetes manifests → Network Topology + - Terraform/CloudFormation → Infrastructure + +3. **Functional View**: + - API routes, CLI commands → Functional Elements + - Class/module structure → Element Interactions + +4. **Information View**: + - Database schemas, ORM models → Data Entities + - Migration files → Data Lifecycle + +**Fill gaps with user interaction**: Ask clarifying questions for aspects that cannot be inferred from code. + +### Phase 3: Apply Perspectives (Security & Performance) + +For each perspective, analyze how architectural decisions address quality concerns: + +#### Security Perspective + +- Review each viewpoint for security implications +- Document authentication/authorization approach +- Identify threat model and mitigations +- Validate against constitution security requirements + +#### Performance & Scalability Perspective + +- Define performance requirements (latency, throughput) +- Document scalability model (horizontal/vertical) +- Identify capacity planning approach +- Map performance concerns to specific views (Concurrency, Deployment) + +### Phase 4: Update Loop (for `update` action) + +**Objective**: Keep architecture synchronized with implementation reality + +1. **Diff Analysis**: + - Compare current `.cx-spec/memory/architecture.md` with recent code/spec changes + - Identify what changed since last architecture update + +2. **Impact Analysis**: + - New database table? → Update **Information View** + - New microservice? → Update **Functional View** and **Deployment View** + - New message queue? → Update **Concurrency View** + - New dependency? → Update **Development View** + +3. **Refinement**: + - Update affected sections with specific changes + - Add ADR (Architecture Decision Record) if significant decision made + - Update "Last Updated" timestamp + +### Phase 5: Review & Validation (for `review` action) + +1. **Constitution Alignment**: + - Load `.cx-spec/memory/constitution.md` + - Verify architecture adheres to all constitutional principles + - Report violations or conflicts + +2. **Perspective Coverage**: + - Validate Security perspective is addressed in all relevant views + - Validate Performance perspective is addressed + - Identify gaps or insufficient detail + +3. **Completeness Check**: + - All 7 viewpoints present? + - All mandatory sections filled in? + - Stakeholder concerns addressed? + +4. **Report**: + - Summary of findings + - List of gaps or issues + - Recommendations for improvement + +## Output Format + +### File Location + +- **Primary Output**: `.cx-spec/memory/architecture.md` +- **Tech Stack Location**: Section C (Tech Stack Summary) within architecture.md + +**Note**: Tech stack information is populated directly in architecture.md Section C. No separate tech-stack.md file is generated. + +### Architecture Document Structure + +Follow the template structure exactly: + +1. Introduction (Purpose, Scope, Definitions) +2. Stakeholders & Concerns (table) +3. Architectural Views (7 viewpoints) +4. Architectural Perspectives (2 perspectives) +5. Global Constraints & Principles +6. Architecture Decision Records (ADRs) +7. Appendix (Glossary, References, Tech Stack) + +### Progress Updates + +During generation, provide progress indicators: + +- "✅ Context View completed" +- "✅ Functional View completed" +- "🔄 Scanning codebase for deployment configuration..." +- "✅ Architecture generated: .cx-spec/memory/architecture.md" + +## Key Rules + +### Constitution Compliance + +- Architecture MUST align with `.cx-spec/memory/constitution.md` principles +- Document any deviations as ADRs with justification +- Constitutional violations are blocking issues + +### Traceability + +- Each architectural decision should trace back to stakeholder concern +- Use ADRs to document significant decisions and trade-offs +- Cross-reference between views when elements appear in multiple places + +### Practical Architecture + +- Focus on **decisions that matter** - avoid boilerplate +- Use **concrete examples** over generic descriptions +- Include **diagrams** (ASCII art is fine) for complex relationships +- Keep it **maintainable** - architecture should evolve with system + +### Mode-Aware Behavior + +Architecture documentation is optional in all modes: + +- Use when system complexity requires formal documentation +- Skip for simple, single-service applications +- Architecture commands work silently regardless of mode + +## Workflow Guidance & Transitions + +### After `/cx-spec.architect init` + +Recommended next steps: + +1. Review generated architecture with stakeholders +2. Refine sections that need more detail +3. Run `/cx-spec.architect review` to validate +4. Switch to normal workflow: `/cx-spec.specify` → `/cx-spec.plan` → `/cx-spec.tasks` → `/cx-spec.implement` + +### After `/cx-spec.architect map` + +For brownfield projects: + +1. Review extracted architecture for accuracy +2. Fill in gaps that couldn't be inferred +3. Add missing perspectives and constraints +4. Use as baseline for modernization planning + +### After `/cx-spec.architect update` + +After implementing features: + +1. Verify architecture reflects current reality +2. Check for architectural drift +3. Update ADRs if significant decisions changed +4. Consider running `/cx-spec.architect review` + +## Context + +$ARGUMENTS diff --git a/.claude/commands/cx-spec.checklist.md b/.claude/commands/cx-spec.checklist.md new file mode 100644 index 000000000..40dfb1d38 --- /dev/null +++ b/.claude/commands/cx-spec.checklist.md @@ -0,0 +1,411 @@ +--- +description: Generate feature checklist from requirements +--- + +## Checklist Purpose: "Unit Tests for English" + +**CRITICAL CONCEPT**: Checklists are **UNIT TESTS FOR REQUIREMENTS WRITING** - they validate the quality, clarity, and completeness of requirements in a given domain. + +**NOT for verification/testing**: + +- ❌ NOT "Verify the button clicks correctly" +- ❌ NOT "Test error handling works" +- ❌ NOT "Confirm the API returns 200" +- ❌ NOT checking if code/implementation matches the spec + +**FOR requirements quality validation**: + +- ✅ "Are visual hierarchy requirements defined for all card types?" (completeness) +- ✅ "Is 'prominent display' quantified with specific sizing/positioning?" (clarity) +- ✅ "Are hover state requirements consistent across all interactive elements?" (consistency) +- ✅ "Are accessibility requirements defined for keyboard navigation?" (coverage) +- ✅ "Does the spec define what happens when logo image fails to load?" (edge cases) + +**Metaphor**: If your spec is code written in English, the checklist is its unit test suite. You're testing whether the requirements are well-written, complete, unambiguous, and ready for implementation - NOT whether the implementation works. + +## User Input + +```text +$ARGUMENTS +``` + + +You **MUST** consider the user input before proceeding (if not empty). + +## Shell Compatibility + +- Use `.cx-spec/scripts/bash/...` on macOS/Linux. +- Use `.cx-spec/scripts/powershell/...` on Windows. +- If a step shows only one shell form, use the equivalent script in the other shell. + + + + + +## Execution Steps + +1. **Setup**: Run `.cx-spec/scripts/bash/check-prerequisites.sh --json` from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. + - All file paths must be absolute. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + - Auto-detect workflow mode and framework options from spec.md using `detect_workflow_config()` + +2. **Clarify intent (dynamic)**: Derive up to THREE initial contextual clarifying questions (no pre-baked catalog). They MUST: + - Be generated from the user's phrasing + extracted signals from spec/plan/tasks + - Only ask about information that materially changes checklist content + - Be skipped individually if already unambiguous in `$ARGUMENTS` + - Prefer precision over breadth + + Generation algorithm: + 1. Extract signals: feature domain keywords (e.g., auth, latency, UX, API), risk indicators ("critical", "must", "compliance"), stakeholder hints ("QA", "review", "security team"), and explicit deliverables ("a11y", "rollback", "contracts"). + 2. Cluster signals into candidate focus areas (max 4) ranked by relevance. + 3. Identify probable audience & timing (author, reviewer, QA, release) if not explicit. + 4. Detect missing dimensions: scope breadth, depth/rigor, risk emphasis, exclusion boundaries, measurable acceptance criteria. + 5. Formulate questions chosen from these archetypes: + - Scope refinement (e.g., "Should this include integration touchpoints with X and Y or stay limited to local module correctness?") + - Risk prioritization (e.g., "Which of these potential risk areas should receive mandatory gating checks?") + - Depth calibration (e.g., "Is this a lightweight pre-commit sanity list or a formal release gate?") + - Audience framing (e.g., "Will this be used by the author only or peers during PR review?") + - Boundary exclusion (e.g., "Should we explicitly exclude performance tuning items this round?") + - Scenario class gap (e.g., "No recovery flows detected—are rollback / partial failure paths in scope?") + + Question formatting rules: + - If presenting options, generate a compact table with columns: Option | Candidate | Why It Matters + - Limit to A–E options maximum; omit table if a free-form answer is clearer + - Never ask the user to restate what they already said + - Avoid speculative categories (no hallucination). If uncertain, ask explicitly: "Confirm whether X belongs in scope." + + Defaults when interaction impossible: + - Depth: Standard + - Audience: Reviewer (PR) if code-related; Author otherwise + - Focus: Top 2 relevance clusters + + Output the questions (label Q1/Q2/Q3). After answers: if ≥2 scenario classes (Alternate / Exception / Recovery / Non-Functional domain) remain unclear, you MAY ask up to TWO more targeted follow‑ups (Q4/Q5) with a one-line justification each (e.g., "Unresolved recovery path risk"). Do not exceed five total questions. Skip escalation if user explicitly declines more. + +3. **Understand user request**: Combine `$ARGUMENTS` + clarifying answers: + - Derive checklist theme (e.g., security, review, deploy, ux) + - Consolidate explicit must-have items mentioned by user + - Map focus selections to category scaffolding + - Infer any missing context from spec/plan/tasks (do NOT hallucinate) + +4. **Load feature context**: Read from FEATURE_DIR: + - spec.md: Feature requirements and scope + - plan.md (if exists): Technical details, dependencies + - tasks.md (if exists): Implementation tasks + - .mcp.json (if exists): MCP server configurations + - .cx-spec/config/config.json: Current mode and enabled options (under `workflow` and `options` sections) + + **Context Loading Strategy**: + - Load only necessary portions relevant to active focus areas (avoid full-file dumping) + - Prefer summarizing long sections into concise scenario/requirement bullets + - Use progressive disclosure: add follow-on retrieval only if gaps detected + - If source docs are large, generate interim summary items instead of embedding raw text + - For MCP validation: Check .mcp.json structure and server configurations + +5. **Apply Mode-Aware Checklist Generation**: Use detected workflow config to adapt checklist content based on enabled framework options: + + **Parse Workflow Config JSON**: + - `mode`: "build" or "spec" (affects default option values) + - `tdd`: true/false - include TDD requirement checks + - `contracts`: true/false - include API contract checks + - `data_models`: true/false - include data model checks + - `risk_tests`: true/false - include risk-based testing checks + + **TDD Option (if tdd=true)**: + - Include items checking if test requirements are specified in the spec + - Validate that acceptance criteria are testable + - Check for test scenario coverage in requirements + + **API Contracts Option (if contracts=true)**: + - Include items validating OpenAPI/GraphQL contract requirements + - Check for API specification completeness and clarity + - Validate contract versioning and compatibility requirements + + **Data Models Option (if data_models=true)**: + - Include items checking entity and relationship specifications + - Validate data model completeness and consistency + - Check for data validation and constraint requirements + + **Risk-Based Testing Option (if risk_tests=true)**: + - Include items validating risk assessment coverage + - Check for mitigation strategy specifications + - Validate edge case and failure scenario requirements + +6. **Generate checklist** - Create "Unit Tests for Requirements": + - Create `FEATURE_DIR/checklists/` directory if it doesn't exist + - Generate unique checklist filename: + - Use short, descriptive name based on domain (e.g., `ux.md`, `api.md`, `security.md`) + - Format: `[domain].md` + - If file exists, append to existing file + - Number items sequentially starting from CHK001 + - Each `/cx-spec.checklist` run creates a NEW file (never overwrites existing checklists) + - For MCP validation: Include infrastructure quality checks when relevant to the checklist focus + + **CORE PRINCIPLE - Test the Requirements, Not the Implementation**: + Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES for: + - **Completeness**: Are all necessary requirements present? + - **Clarity**: Are requirements unambiguous and specific? + - **Consistency**: Do requirements align with each other? + - **Measurability**: Can requirements be objectively verified? + - **Coverage**: Are all scenarios/edge cases addressed? + + **HOW TO WRITE CHECKLIST ITEMS - "Unit Tests for English"**: + + ❌ **WRONG** (Testing implementation): + - "Verify landing page displays 3 episode cards" + - "Test hover states work on desktop" + - "Confirm logo click navigates home" + + ✅ **CORRECT** (Testing requirements quality): + - "Are the exact number and layout of featured episodes specified?" [Completeness] + - "Is 'prominent display' quantified with specific sizing/positioning?" [Clarity] + - "Are hover state requirements consistent across all interactive elements?" [Consistency] + - "Are keyboard navigation requirements defined for all interactive UI?" [Coverage] + - "Is the fallback behavior specified when logo image fails to load?" [Edge Cases] + - "Are loading states defined for asynchronous episode data?" [Completeness] + - "Does the spec define visual hierarchy for competing UI elements?" [Clarity] + + **ITEM STRUCTURE**: + Each item should follow this pattern: + - Question format asking about requirement quality + - Focus on what's WRITTEN (or not written) in the spec/plan + - Include quality dimension in brackets [Completeness/Clarity/Consistency/etc.] + - Reference spec section `[Spec §X.Y]` when checking existing requirements + - Use `[Gap]` marker when checking for missing requirements + + **EXAMPLES BY QUALITY DIMENSION**: + + Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" + + Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" + + Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" + + Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" + + Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" + + Completeness: + - "Are error handling requirements defined for all API failure modes? [Gap]" + - "Are accessibility requirements specified for all interactive elements? [Completeness]" + - "Are mobile breakpoint requirements defined for responsive layouts? [Gap]" + + Clarity: + - "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]" + - "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]" + - "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]" + + Consistency: + - "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]" + - "Are card component requirements consistent between landing and detail pages? [Consistency]" + + Coverage: + - "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]" + - "Are concurrent user interaction scenarios addressed? [Coverage, Gap]" + - "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]" + + Measurability: + - "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]" + - "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]" + + Infrastructure (MCP Configuration): + - "Is .mcp.json file present and contains valid JSON? [Completeness, Infrastructure]" + - "Are MCP server URLs properly formatted and accessible? [Clarity, Infrastructure]" + - "Is issue tracker MCP server configured for project tracking? [Coverage, Infrastructure]" + - "Are async agent MCP servers configured for task delegation? [Completeness, Infrastructure]" + - "Do MCP server configurations include required type and url fields? [Consistency, Infrastructure]" + + Framework Options (Mode-Aware): + - "Are test requirements specified for all acceptance criteria? [Completeness, TDD]" (when TDD enabled) + - "Are API contract specifications complete and versioned? [Completeness, Contracts]" (when contracts enabled) + - "Are entity relationships and data models fully specified? [Completeness, Data Models]" (when data models enabled) + - "Are risk mitigation strategies documented for critical paths? [Coverage, Risk Testing]" (when risk tests enabled) + + **Scenario Classification & Coverage** (Requirements Quality Focus): + - Check if requirements exist for: Primary, Alternate, Exception/Error, Recovery, Non-Functional scenarios + - For each scenario class, ask: "Are [scenario type] requirements complete, clear, and consistent?" + - If scenario class missing: "Are [scenario type] requirements intentionally excluded or missing? [Gap]" + - Include resilience/rollback when state mutation occurs: "Are rollback requirements defined for migration failures? [Gap]" + + **MCP Configuration Validation** (Infrastructure Quality Focus): + - Check if `.mcp.json` file exists and is properly configured + - Validate MCP server configurations for issue trackers and async agents + - Ensure required fields (type, url) are present for each server + - Verify URL formats and server types are valid + - Check for proper integration with issue tracking systems (GitHub, Jira, etc.) + - Validate async agent configurations for delegation support + + **Traceability Requirements**: + - MINIMUM: ≥80% of items MUST include at least one traceability reference + - Each item should reference: spec section `[Spec §X.Y]`, or use markers: `[Gap]`, `[Ambiguity]`, `[Conflict]`, `[Assumption]` + - If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]" + + **Surface & Resolve Issues** (Requirements Quality Problems): + Ask questions about the requirements themselves: + - Ambiguities: "Is the term 'fast' quantified with specific metrics? [Ambiguity, Spec §NFR-1]" + - Conflicts: "Do navigation requirements conflict between §FR-10 and §FR-10a? [Conflict]" + - Assumptions: "Is the assumption of 'always available podcast API' validated? [Assumption]" + - Dependencies: "Are external podcast API requirements documented? [Dependency, Gap]" + - Missing definitions: "Is 'visual hierarchy' defined with measurable criteria? [Gap]" + + **MCP Configuration Issues** (Infrastructure Quality Problems): + Ask questions about MCP setup quality: + - Missing config: "Is .mcp.json file present in the project root? [Gap, Infrastructure]" + - Invalid servers: "Do MCP server configurations have valid URLs and types? [Consistency, Infrastructure]" + - Missing integrations: "Is issue tracker MCP configured for the project's tracking system? [Coverage, Infrastructure]" + - Async delegation: "Are async agent MCP servers configured for task delegation? [Completeness, Infrastructure]" + + **MCP Configuration Validation Logic**: + - When checklist focus includes infrastructure or deployment aspects, include MCP validation items + - Check .mcp.json file existence and validity + - Validate each MCP server configuration for required fields and proper formatting + - Ensure issue tracker integration is configured for the project's tracking system + - Verify async agent configurations are present for delegation support + - Flag any MCP configuration issues that could impact development workflow + + **Content Consolidation**: + - Soft cap: If raw candidate items > 40, prioritize by risk/impact + - Merge near-duplicates checking the same requirement aspect + - If >5 low-impact edge cases, create one item: "Are edge cases X, Y, Z addressed in requirements? [Coverage]" + - For MCP items: Consolidate server validation checks into logical groupings + + **🚫 ABSOLUTELY PROHIBITED** - These make it an implementation test, not a requirements test: + - ❌ Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior + - ❌ References to code execution, user actions, system behavior + - ❌ "Displays correctly", "works properly", "functions as expected" + - ❌ "Click", "navigate", "render", "load", "execute" + - ❌ Test cases, test plans, QA procedures + - ❌ Implementation details (frameworks, APIs, algorithms) + + **✅ REQUIRED PATTERNS** - These test requirements quality: + - ✅ "Are [requirement type] defined/specified/documented for [scenario]?" + - ✅ "Is [vague term] quantified/clarified with specific criteria?" + - ✅ "Are requirements consistent between [section A] and [section B]?" + - ✅ "Can [requirement] be objectively measured/verified?" + - ✅ "Are [edge cases/scenarios] addressed in requirements?" + - ✅ "Does the spec define [missing aspect]?" + +7. **Structure Reference**: Generate the checklist following the canonical template in `{REPO_ROOT}/.cx-spec/templates/checklist-template.md` for title, meta section, category headings, and ID formatting. If template is unavailable, use: H1 title, purpose/created meta lines, `##` category sections containing `- [ ] CHK### ` lines with globally incrementing IDs starting at CHK001. + +8. **Report**: Output full path to created checklist, item count, and remind user that each run creates a new file. Summarize: + - Focus areas selected + - Depth level + - Actor/timing + - Any explicit user-specified must-have items incorporated + - MCP configuration validation status (if included in checklist) + - Framework options validation status (based on enabled mode options) + +**Important**: Each `/cx-spec.checklist` command invocation creates a checklist file using short, descriptive names unless file already exists. This allows: + +- Multiple checklists of different types (e.g., `ux.md`, `test.md`, `security.md`) +- Simple, memorable filenames that indicate checklist purpose +- Easy identification and navigation in the `checklists/` folder + +To avoid clutter, use descriptive types and clean up obsolete checklists when done. + +## Example Checklist Types & Sample Items + +**UX Requirements Quality:** `ux.md` + +Sample items (testing the requirements, NOT the implementation): + +- "Are visual hierarchy requirements defined with measurable criteria? [Clarity, Spec §FR-1]" +- "Is the number and positioning of UI elements explicitly specified? [Completeness, Spec §FR-1]" +- "Are interaction state requirements (hover, focus, active) consistently defined? [Consistency]" +- "Are accessibility requirements specified for all interactive elements? [Coverage, Gap]" +- "Is fallback behavior defined when images fail to load? [Edge Case, Gap]" +- "Can 'prominent display' be objectively measured? [Measurability, Spec §FR-4]" + +**API Requirements Quality:** `api.md` + +Sample items: + +- "Are error response formats specified for all failure scenarios? [Completeness]" +- "Are rate limiting requirements quantified with specific thresholds? [Clarity]" +- "Are authentication requirements consistent across all endpoints? [Consistency]" +- "Are retry/timeout requirements defined for external dependencies? [Coverage, Gap]" +- "Is versioning strategy documented in requirements? [Gap]" + +**Performance Requirements Quality:** `performance.md` + +Sample items: + +- "Are performance requirements quantified with specific metrics? [Clarity]" +- "Are performance targets defined for all critical user journeys? [Coverage]" +- "Are performance requirements under different load conditions specified? [Completeness]" +- "Can performance requirements be objectively measured? [Measurability]" +- "Are degradation requirements defined for high-load scenarios? [Edge Case, Gap]" + +**Security Requirements Quality:** `security.md` + +Sample items: + +- "Are authentication requirements specified for all protected resources? [Coverage]" +- "Are data protection requirements defined for sensitive information? [Completeness]" +- "Is the threat model documented and requirements aligned to it? [Traceability]" +- "Are security requirements consistent with compliance obligations? [Consistency]" +- "Are security failure/breach response requirements defined? [Gap, Exception Flow]" + +**MCP Configuration Quality:** `mcp.md` + +Sample items: + +- "Is .mcp.json file present and properly configured? [Completeness, Infrastructure]" +- "Are MCP server URLs valid and accessible? [Clarity, Infrastructure]" +- "Is issue tracker MCP server configured for the project's tracking system? [Coverage, Infrastructure]" +- "Are async agent MCP servers properly configured for delegation? [Completeness, Infrastructure]" +- "Do MCP server configurations include required type and url fields? [Consistency, Infrastructure]" +- "Are MCP server types valid (http, websocket, stdio)? [Measurability, Infrastructure]" + +**Framework Options Quality:** `options.md` (when mode options are enabled) + +Sample items (varies based on enabled options): + +- "Are test scenarios specified for all acceptance criteria? [Completeness, TDD]" (TDD enabled) +- "Are API contract specifications complete with versioning? [Completeness, Contracts]" (contracts enabled) +- "Are entity relationships and constraints fully documented? [Completeness, Data Models]" (data models enabled) +- "Are risk assessment and mitigation strategies specified? [Coverage, Risk Testing]" (risk tests enabled) +- "Are framework option requirements consistent with project complexity level? [Consistency, Options]" + +## Anti-Examples: What NOT To Do + +**❌ WRONG - These test implementation, not requirements:** + +```markdown +- [ ] CHK001 - Verify landing page displays 3 episode cards [Spec §FR-001] +- [ ] CHK002 - Test hover states work correctly on desktop [Spec §FR-003] +- [ ] CHK003 - Confirm logo click navigates to home page [Spec §FR-010] +- [ ] CHK004 - Check that related episodes section shows 3-5 items [Spec §FR-005] +``` + +**✅ CORRECT - These test requirements quality:** + +```markdown +- [ ] CHK001 - Are the number and layout of featured episodes explicitly specified? [Completeness, Spec §FR-001] +- [ ] CHK002 - Are hover state requirements consistently defined for all interactive elements? [Consistency, Spec §FR-003] +- [ ] CHK003 - Are navigation requirements clear for all clickable brand elements? [Clarity, Spec §FR-010] +- [ ] CHK004 - Is the selection criteria for related episodes documented? [Gap, Spec §FR-005] +- [ ] CHK005 - Are loading state requirements defined for asynchronous episode data? [Gap] +- [ ] CHK006 - Can "visual hierarchy" requirements be objectively measured? [Measurability, Spec §FR-001] +``` + +**Key Differences:** + +- Wrong: Tests if the system works correctly +- Correct: Tests if the requirements are written correctly +- Wrong: Verification of behavior +- Correct: Validation of requirement quality +- Wrong: "Does it do X?" +- Correct: "Is X clearly specified?" diff --git a/.claude/commands/cx-spec.clarify.md b/.claude/commands/cx-spec.clarify.md new file mode 100644 index 000000000..be68dcaba --- /dev/null +++ b/.claude/commands/cx-spec.clarify.md @@ -0,0 +1,414 @@ +--- +description: Ask clarifying questions for underspecified areas +handoffs: + - label: Build Technical Plan + agent: cx-spec.plan + prompt: Create a plan for the spec. I am building with... +--- + +## User Input + +```text +$ARGUMENTS +``` + + +You **MUST** consider the user input before proceeding (if not empty). + +## Shell Compatibility + +- Use `.cx-spec/scripts/bash/...` on macOS/Linux. +- Use `.cx-spec/scripts/powershell/...` on Windows. +- If a step shows only one shell form, use the equivalent script in the other shell. + + + + + +## Mode Detection + +1. **Auto-Detect from Spec**: Use the `detect_workflow_config()` function to automatically detect the workflow mode and framework options from the current feature's `spec.md` file. This reads the `**Workflow Mode**` and `**Framework Options**` metadata lines. + +2. **Mode-Aware Behavior**: + - **Build Mode**: Minimal clarification - focus only on critical blockers, limit to 1-2 questions maximum + - **Spec Mode**: Full clarification workflow - comprehensive ambiguity detection and resolution + +## Outline + +Goal: Detect and reduce ambiguity or missing decision points in the active feature specification. Validate spec against project constitution and architecture (three-pillar validation). Record clarifications directly in the spec file. + +Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/cx-spec.plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases. + +## Three-Pillar Validation + +This command validates the spec across three pillars: + +1. **Specification Completeness** (existing) - Functional scope, data model, UX, non-functionals, constraints +2. **Constitution Alignment** (NEW) - Compliance with team principles, patterns, and governance +3. **Architecture Alignment** (NEW) - Fit within system boundaries, component patterns, and diagram consistency + +**Load Order**: + +- Parse JSON from `.cx-spec/scripts/bash/check-prerequisites.sh --json --paths-only` to get paths including `CONSTITUTION`, `ARCHITECTURE`, and existence flags +- If `CONSTITUTION_EXISTS: true`, load constitution rules and validate spec against them +- If `ARCHITECTURE_EXISTS: true`, load architecture views/diagrams and validate spec alignment +- If both missing, fall back to spec-only validation (current behavior) + +**Priority Order** (highest impact first): + +1. Architecture boundary violations (blocks system design) +2. Constitution constraint violations (blocks governance) +3. Diagram-text inconsistencies (architecture quality) +4. Missing architecture integration points (scalability/operational impact) +5. Spec completeness gaps (lowest priority) + +**Question Limit**: + +- No architecture present: max 5 questions (build: 2, spec: 5) +- Architecture present: max 10 questions (build: 2, spec: 10) - expanded capacity + +**Auto-Fix Capability**: +When detecting diagram-text inconsistency, automatically: + +- Suggest specific diagram update +- Regenerate diagram block with corrections +- Record change in clarifications section +- Skip asking question if auto-fix covers it + +Execution steps: + +0. Run custom constitution principles gate once from repo root: + - Bash: `.cx-spec/scripts/bash/check-custom-constitution-principles.sh --json` + - PowerShell: `.cx-spec/scripts/powershell/check-custom-constitution-principles.ps1 -Json` + - Parse: `active_principles`. + - If `active_principles` is non-empty, load each `active_principles[].content` into context and treat all explicit `MUST`/`MUST NOT` statements as non-negotiable constraints. + - If a principle states to fail/stop when a condition is unmet, and that condition is unmet or unverifiable, STOP immediately and do not continue. + - If continuing, preserve/update a `## Custom Principle Evidence` section in `spec.md` documenting principle id, principle file, and satisfied MUST clauses. + +1. Run `.cx-spec/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields: + - `FEATURE_DIR` + - `FEATURE_SPEC` + - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.) + - If JSON parsing fails, abort and instruct user to re-run `/cx-spec.specify` or verify feature branch environment. + - For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). + +2. Load governance and architecture documents (if available): + + **Constitution Loading** (if `CONSTITUTION_EXISTS: true`): + - Load constitution from path provided in JSON + - Extract principles, constraints, and patterns using `CONSTITUTION_RULES` + - Prepare for cross-validation with spec + + **Architecture Loading** (if `ARCHITECTURE_EXISTS: true`): + - Load architecture.md from path provided in JSON + - Extract 7 viewpoints using `ARCHITECTURE_VIEWS` + - Extract diagrams using `ARCHITECTURE_DIAGRAMS` + - Identify components, entities, and integration points + - Prepare for alignment validation + + **Graceful Degradation**: + - If constitution missing: Skip constitution validation + - If architecture missing: Skip architecture validation + - If both missing: Proceed with spec-only validation (current behavior) + +3. Load the current spec file. Perform three-pillar validation scan: + + **PILLAR 1: Specification Completeness** (existing taxonomy) + + For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization. + + Functional Scope & Behavior: + - Core user goals & success criteria + - Explicit out-of-scope declarations + - User roles / personas differentiation + + Domain & Data Model: + - Entities, attributes, relationships + - Identity & uniqueness rules + - Lifecycle/state transitions + - Data volume / scale assumptions + + Interaction & UX Flow: + - Critical user journeys / sequences + - Error/empty/loading states + - Accessibility or localization notes + + Non-Functional Quality Attributes: + - Performance (latency, throughput targets) + - Scalability (horizontal/vertical, limits) + - Reliability & availability (uptime, recovery expectations) + - Observability (logging, metrics, tracing signals) + - Security & privacy (authN/Z, data protection, threat assumptions) + - Compliance / regulatory constraints (if any) + + Integration & External Dependencies: + - External services/APIs and failure modes + - Data import/export formats + - Protocol/versioning assumptions + + Edge Cases & Failure Handling: + - Negative scenarios + - Rate limiting / throttling + - Conflict resolution (e.g., concurrent edits) + + Constraints & Tradeoffs: + - Technical constraints (language, storage, hosting) + - Explicit tradeoffs or rejected alternatives + + Terminology & Consistency: + - Canonical glossary terms + - Avoided synonyms / deprecated terms + + Completion Signals: + - Acceptance criteria testability + - Measurable Definition of Done style indicators + + Misc / Placeholders: + - TODO markers / unresolved decisions + - Ambiguous adjectives ("robust", "intuitive") lacking quantification + + For each category with Partial or Missing status, add a candidate question opportunity unless: + - Clarification would not materially change implementation or validation strategy + - Information is better deferred to planning phase (note internally) + + **PILLAR 2: Constitution Alignment** (NEW - if constitution exists) + + Validate spec against constitutional rules: + + Principle Compliance: + - Does spec respect declared team principles? + - Are standard architectural patterns applied? + - Is coding philosophy consistent with constitution? + + Constraint Adherence: + - Technical constraints: Does spec violate technology/platform restrictions? + - Security constraints: Does spec meet required security posture? + - Operational constraints: Does spec respect deployment/operational requirements? + - Compliance constraints: Are regulatory requirements addressed? + + Pattern Consistency: + - Are approved architectural patterns followed? + - Do component designs match constitutional patterns? + - Is error handling consistent with established patterns? + + **Flag conflicts** where spec contradicts constitution: + - Record as HIGH PRIORITY issues (blocking governance) + - Example: Constitution requires OAuth2, spec uses API keys + - Example: Constitution mandates audit logging, spec doesn't mention it + + **PILLAR 3: Architecture Alignment** (NEW - if architecture exists) + + Validate spec against architectural boundaries: + + System Boundaries (Context View): + - Does spec operate within defined external entity interactions? + - Are new external dependencies within acceptable scope? + - Do integration points match Context View? + + Component Alignment (Functional View): + - Do new/modified components fit existing architecture? + - Are component responsibilities clear and non-overlapping? + - Do interactions follow established patterns? + + Data Model Consistency (Information View): + - Do entities/relationships align with Information View? + - Are data lifecycle requirements considered? + - Do data flows match architectural design? + + Process Coordination (Concurrency View): + - Are concurrency requirements architecturally feasible? + - Do threading/async patterns match Concurrency View? + - Are synchronization mechanisms appropriate? + + Code Organization (Development View): + - Does spec respect code organization structure? + - Are module dependencies appropriate? + - Does testing approach align with Development View? + + Deployment Feasibility (Deployment View): + - Can performance requirements be met with current deployment? + - Are scalability expectations realistic? + - Do infrastructure needs match Deployment View? + + Operational Readiness (Operational View): + - Are monitoring/alerting requirements specified? + - Is operational complexity acceptable? + - Are backup/recovery needs considered? + + **Diagram Consistency Check**: + - Compare architecture diagram content with textual descriptions + - Detect missing components: Functional View text mentions component not in diagram + - Detect missing entities: Information View entities missing from ER diagram + - Detect flow mismatches: Concurrency View text/diagram inconsistencies + + **Auto-Fix Capability**: + When diagram inconsistency detected: + - Generate updated diagram code (mermaid or ascii based on format) + - Insert corrected diagram in place of outdated one + - Record in clarifications: "Auto-updated [View] diagram to include [component]" + - Skip asking question since auto-fix resolved it + + **Flag architectural issues**: + - Boundary violations: HIGH PRIORITY (system design impact) + - Component misalignments: MEDIUM PRIORITY (refactoring needed) + - Diagram inconsistencies: MEDIUM PRIORITY (auto-fixable) + - Missing integration details: LOW PRIORITY (can defer to planning) + +4. Generate (internally) a prioritized queue of candidate clarification questions (mode-aware limits): + + **Build Mode Question Generation:** + - Maximum of 2 total questions across the whole session + - Focus ONLY on scope-defining decisions that would prevent basic functionality + - Skip detailed technical, performance, or edge case questions + - Prioritize: core functionality > basic UX > essential data requirements + + **Spec Mode Question Generation:** + - Maximum of 5 questions if no architecture present + - Maximum of 10 questions if architecture present (expanded capacity) + - Each question must be answerable with EITHER: + - A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR + - A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words") + - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation + - **Three-Pillar Priority Order** (highest impact first): + 1. Architecture boundary violations + 2. Constitution constraint violations + 3. Diagram-text inconsistencies (auto-fixable) + 4. Missing architecture integration points + 5. Spec completeness gaps + - Ensure pillar coverage balance: prioritize constitutional/architectural issues over spec gaps + - Favor clarifications that reduce downstream rework risk or prevent governance violations + - If more than 10 issues remain (when architecture present), select top 10 by priority order above + +4. Sequential questioning loop (interactive, mode-aware): + + **Build Mode Questioning:** + - Present EXACTLY ONE question at a time (maximum 2 total) + - Keep questions extremely simple and focused on basic functionality + - Use short-answer format when possible to minimize interaction + - Stop after 2 questions or when core functionality is clear + + **Spec Mode Questioning:** + - Present EXACTLY ONE question at a time + - For multiple‑choice questions: + - **Analyze all options** and determine the **most suitable option** based on: + - Best practices for the project type + - Common patterns in similar implementations + - Risk reduction (security, performance, maintainability) + - Alignment with any explicit project goals or constraints visible in the spec + - Present your **recommended option prominently** at the top with clear reasoning (1-2 sentences explaining why this is the best choice) + - Format as: `**Recommended:** Option [X] - ` + - Then render all options as a Markdown table: + + | Option | Description | + |--------|-------------| + | A |