name: implement
description: Implement a specification using PMAT EXTREME TDD methodology
category: development
priority: critical
methodology: EXTREME TDD + Spec-Driven Development + Toyota Way
constraints:
  - specification document required
  - roadmap creation mandatory
  - tests written first (RED phase)
  - zero regressions
  - quality gates must pass
variables:
  SPEC_PATH: ""
  PROJECT_TYPE: "existing"  # "new" or "existing"
  PROJECT_NAME: ""
  TEST_CMD: "cargo test"
  BUILD_CMD: "cargo build"
  MIN_COVERAGE: "85"
  MIN_MUTATION_SCORE: "80"
heuristics:
  - analyze specification completely
  - create roadmap from spec requirements
  - scaffold new repo if needed
  - write failing tests first
  - implement incrementally
  - verify quality gates
prompt: |
  Implement a specification following PMAT EXTREME TDD methodology.

  ## STEP 0: UNDERSTAND THE SPECIFICATION

  **Read the specification document:**
  ```bash
  # Specification location: ${SPEC_PATH}
  cat ${SPEC_PATH}
  ```

  **Extract key information:**
  - [ ] Purpose: What problem does this solve?
  - [ ] Scope: What's included/excluded?
  - [ ] Requirements: What are the acceptance criteria?
  - [ ] Dependencies: What external systems/libraries needed?
  - [ ] Performance targets: Any speed/memory constraints?
  - [ ] Quality targets: Coverage, mutation score, complexity limits

  **Document understanding:**
  Create a brief summary of the spec in your own words to verify comprehension.

  ## STEP 1: PROJECT SETUP

  ### If ${PROJECT_TYPE} == "new" (New Repository)

  **Create project structure:**
  ```bash
  # Rust project
  cargo new ${PROJECT_NAME}
  cd ${PROJECT_NAME}

  # Initialize git
  git init
  git add .
  git commit -m "chore: Initial project scaffold"

  # Create standard directories
  mkdir -p {docs,tests,benches,examples,.github/workflows}
  mkdir -p docs/specifications
  ```

  **Create foundational files:**

  **README.md:**
  ```markdown
  # ${PROJECT_NAME}

  [Brief description from spec]

  ## Features

  - [ ] Feature 1 (from spec)
  - [ ] Feature 2 (from spec)

  ## Installation

  \`\`\`bash
  cargo install ${PROJECT_NAME}
  \`\`\`

  ## Usage

  \`\`\`bash
  ${PROJECT_NAME} --help
  \`\`\`

  ## Development

  ### Prerequisites
  - Rust 1.75+
  - cargo-nextest
  - cargo-llvm-cov

  ### Build
  \`\`\`bash
  cargo build --release
  \`\`\`

  ### Test
  \`\`\`bash
  make test-fast
  \`\`\`

  ## Quality Standards

  - Test Coverage: ≥${MIN_COVERAGE}%
  - Mutation Score: ≥${MIN_MUTATION_SCORE}%
  - Clippy: Zero warnings
  - Complexity: All functions ≤20

  ## License

  MIT OR Apache-2.0
  ```

  **Cargo.toml (for Rust projects):**
  ```toml
  [package]
  name = "${PROJECT_NAME}"
  version = "0.1.0"
  edition = "2021"
  rust-version = "1.75"
  authors = ["PMAT Team"]
  license = "MIT OR Apache-2.0"
  description = "[From spec]"
  repository = "https://github.com/paiml/${PROJECT_NAME}"
  keywords = []
  categories = []

  [dependencies]
  # Add from spec requirements

  [dev-dependencies]
  assert_cmd = "2.0"
  predicates = "3.0"
  proptest = "1.0"
  criterion = "0.5"

  [[bench]]
  name = "benchmarks"
  harness = false

  [profile.release]
  lto = true
  codegen-units = 1
  ```

  **Makefile:**
  ```makefile
  .PHONY: test test-fast coverage build clean

  test-fast:
  \tif command -v cargo-nextest >/dev/null 2>&1; then \
  \t\tcargo nextest run --workspace; \
  \telse \
  \t\tcargo test --workspace; \
  \tfi

  coverage:
  \tcargo llvm-cov --all-features --workspace --lcov --output-path lcov.info
  \tcargo llvm-cov report

  build:
  \tcargo build --release

  clean:
  \tcargo clean

  lint:
  \tcargo clippy --all-targets --all-features -- -D warnings

  format:
  \tcargo fmt --all -- --check

  quality-gate: lint format test-fast coverage
  \t@echo "All quality gates passed!"
  ```

  **.gitignore:**
  ```
  target/
  Cargo.lock
  *.swp
  .DS_Store
  lcov.info
  ```

  **CI Pipeline (.github/workflows/ci.yml):**
  ```yaml
  name: CI

  on: [push, pull_request]

  jobs:
    test:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: dtolnay/rust-toolchain@stable
        - run: cargo test --all-features

    quality:
      runs-on: ubuntu-latest
      steps:
        - uses: actions/checkout@v4
        - uses: dtolnay/rust-toolchain@stable
        - run: cargo clippy -- -D warnings
        - run: cargo fmt -- --check
  ```

  **PMAT Configuration:**
  ```bash
  # Install TDG enforcement hooks
  pmat hooks install --tdg-enforcement

  # Create initial TDG baseline
  pmat analyze tdg --path . --output .pmat/baseline.json

  # Verify installation
  ls -la .git/hooks/pre-commit
  ls -la .pmat/baseline.json
  ```

  ### If ${PROJECT_TYPE} == "existing" (Existing PMAT Project)

  **Verify PMAT setup:**
  ```bash
  # Check for PMAT infrastructure
  ls -la .pmat/baseline.json
  ls -la .git/hooks/pre-commit
  ls -la roadmap.yaml

  # If missing, initialize
  pmat hooks install --tdg-enforcement
  pmat analyze tdg --path . --output .pmat/baseline.json
  ```

  ## STEP 2: CREATE ROADMAP FROM SPECIFICATION

  **Analyze specification requirements:**

  Break down the specification into concrete, testable milestones.

  **Create roadmap.yaml:**

  ```yaml
  project: ${PROJECT_NAME}
  version: 0.1.0
  start_date: $(date +%Y-%m-%d)
  methodology: EXTREME TDD + Spec-Driven Development

  objectives:
    - title: "[Objective 1 from spec]"
      description: "[Details]"
      metrics:
        - "Acceptance criterion 1"
        - "Acceptance criterion 2"

  milestones:
    - name: "Sprint 1: Core Infrastructure"
      target_date: $(date -d '+2 weeks' +%Y-%m-%d)
      objectives:
        - "[First objective from spec]"
      deliverables:
        - "Data structures defined"
        - "Core API designed"
        - "RED tests written"
      acceptance_criteria:
        - "All core types compile"
        - "RED tests fail as expected"
        - "Zero clippy warnings"

    - name: "Sprint 2: Core Implementation"
      target_date: $(date -d '+4 weeks' +%Y-%m-%d)
      objectives:
        - "[Second objective from spec]"
      deliverables:
        - "Core logic implemented"
        - "All RED tests GREEN"
        - "Integration tests added"
      acceptance_criteria:
        - "All unit tests pass"
        - "≥${MIN_COVERAGE}% coverage"
        - "Zero regressions"

    - name: "Sprint 3: Advanced Features"
      target_date: $(date -d '+6 weeks' +%Y-%m-%d)
      objectives:
        - "[Third objective from spec]"
      deliverables:
        - "Advanced features implemented"
        - "Performance benchmarks added"
        - "Documentation complete"
      acceptance_criteria:
        - "All acceptance criteria met"
        - "≥${MIN_MUTATION_SCORE}% mutation score"
        - "Benchmarks baseline established"

    - name: "Sprint 4: Quality & Release"
      target_date: $(date -d '+8 weeks' +%Y-%m-%d)
      objectives:
        - "Production-ready release"
      deliverables:
        - "All quality gates pass"
        - "Documentation validated"
        - "Release 0.1.0"
      acceptance_criteria:
        - "Zero SATD comments"
        - "README accurate (pmat validate-readme)"
        - "crates.io publish ready"

  quality_gates:
    - clippy
    - fmt
    - tdg_no_regressions
    - coverage
    - mutation_score
    - all_tests_pass
    - validate_readme
    - repo_score

  risks:
    - risk: "Performance targets not met"
      mitigation: "Early benchmarking, profiling"
      status: "monitoring"

    - risk: "External dependency breaking changes"
      mitigation: "Version pinning, CI alerts"
      status: "monitoring"

  toyota_way_principles:
    jidoka: "Automated quality gates, CI enforcement"
    andon_cord: "Pre-commit hooks block bad code"
    genchi_genbutsu: "Data-driven decisions from benchmarks"
    kaizen: "Continuous iteration, roadmap updates"
    zero_defects: "100% test pass rate, zero regressions"
  ```

  **Commit roadmap:**
  ```bash
  git add roadmap.yaml
  git commit -m "$(cat <<'EOF'
  docs: Add roadmap for spec implementation

  Created comprehensive roadmap with 4 sprints:
  - Sprint 1: Core infrastructure
  - Sprint 2: Core implementation
  - Sprint 3: Advanced features
  - Sprint 4: Quality & release

  Quality Gates:
  - Coverage ≥${MIN_COVERAGE}%
  - Mutation ≥${MIN_MUTATION_SCORE}%
  - Zero regressions

  🤖 Generated with [Claude Code](https://claude.com/claude-code)

  Co-Authored-By: Claude <noreply@anthropic.com>
  EOF
  )"
  ```

  ## STEP 3: SPRINT 1 - CORE INFRASTRUCTURE (RED PHASE)

  ### Design Core Data Structures

  **From specification, identify:**
  - Core domain types (structs, enums)
  - Error types
  - Configuration types
  - Input/Output formats

  **Create type definitions (RED tests first):**

  **Example: tests/core_types_tests.rs**
  ```rust
  //! Core type tests - RED phase

  use ${PROJECT_NAME}::*;

  #[test]
  fn test_core_type_creation() {
      let instance = CoreType::new("test");
      assert_eq!(instance.name(), "test");
  }

  #[test]
  fn test_error_type_implements_error_trait() {
      let err = CustomError::new("test error");
      let _: &dyn std::error::Error = &err;
  }

  #[test]
  fn test_config_from_file() {
      let config = Config::from_file("test.toml");
      assert!(config.is_ok());
  }
  ```

  **Run tests (should FAIL):**
  ```bash
  cargo test
  # Expected: compilation errors (types don't exist yet)
  ```

  **Create minimal type stubs (still RED):**

  **src/lib.rs:**
  ```rust
  //! ${PROJECT_NAME}
  //!
  //! [Description from spec]

  #![deny(missing_docs)]
  #![deny(clippy::all)]

  pub mod types;
  pub mod errors;
  pub mod config;

  pub use types::*;
  pub use errors::*;
  pub use config::*;
  ```

  **src/types.rs:**
  ```rust
  //! Core domain types

  /// Core type for [purpose from spec]
  pub struct CoreType {
      name: String,
  }

  impl CoreType {
      /// Create new instance
      pub fn new(name: impl Into<String>) -> Self {
          Self { name: name.into() }
      }

      /// Get name
      pub fn name(&self) -> &str {
          &self.name
      }
  }
  ```

  **Run tests again:**
  ```bash
  cargo test
  # Tests should compile but some may still fail (RED phase complete)
  ```

  **Verify RED phase:**
  - [ ] Tests compile
  - [ ] Tests fail as expected
  - [ ] Zero clippy warnings
  - [ ] Code is minimal (no premature implementation)

  ## STEP 4: SPRINT 1 - IMPLEMENT CORE (GREEN PHASE)

  **Implement functionality to make tests pass:**

  **Iterate on each failing test:**
  ```bash
  # 1. Identify failing test
  cargo test --lib | grep FAILED

  # 2. Implement minimal code to fix
  # (Edit src/*.rs)

  # 3. Re-run test
  cargo test test_name

  # 4. Repeat until all tests GREEN
  ```

  **Example implementation:**

  ```rust
  // src/errors.rs
  use std::fmt;

  #[derive(Debug)]
  pub struct CustomError {
      message: String,
  }

  impl CustomError {
      pub fn new(message: impl Into<String>) -> Self {
          Self { message: message.into() }
      }
  }

  impl fmt::Display for CustomError {
      fn fmt(&self, f: &mut fmt::Formatter) -> fmt::Result {
          write!(f, "{}", self.message)
      }
  }

  impl std::error::Error for CustomError {}
  ```

  **Verify GREEN phase:**
  ```bash
  cargo test        # All tests pass
  cargo clippy      # Zero warnings
  cargo build       # Clean build
  ```

  ## STEP 5: SPRINT 1 - REFACTOR

  **Once all tests GREEN, refactor:**

  - Extract common patterns
  - Remove duplication
  - Improve naming
  - Add documentation
  - Optimize performance (if needed)

  **Example refactoring:**
  ```rust
  // Before
  impl CoreType {
      pub fn process(&self) -> String {
          let mut result = String::new();
          result.push_str(&self.name);
          result.push_str("_processed");
          result
      }
  }

  // After (more idiomatic)
  impl CoreType {
      pub fn process(&self) -> String {
          format!("{}_processed", self.name)
      }
  }
  ```

  **Verify refactoring didn't break tests:**
  ```bash
  cargo test --workspace
  # All tests still pass
  ```

  **Check code quality:**
  ```bash
  # Complexity check
  pmat analyze complexity --path src/ --threshold 20

  # SATD check
  grep -r "TODO\|FIXME\|HACK" src/
  # Should be zero or all linked to GitHub issues

  # Coverage
  make coverage
  # Should be ≥${MIN_COVERAGE}%
  ```

  ## STEP 6: SPRINT 2 - ADVANCED FEATURES

  **From specification, implement remaining features:**

  **For each feature:**
  1. **RED**: Write failing tests
  2. **GREEN**: Implement minimal code
  3. **REFACTOR**: Clean up
  4. **VERIFY**: Quality gates

  **Example: CLI Integration**

  **RED tests (tests/cli_tests.rs):**
  ```rust
  use assert_cmd::Command;
  use predicates::prelude::*;

  #[test]
  fn test_cli_help() {
      let mut cmd = Command::cargo_bin(env!("CARGO_PKG_NAME")).unwrap();
      cmd.arg("--help")
          .assert()
          .success()
          .stdout(predicate::str::contains("Usage:"));
  }

  #[test]
  fn test_cli_version() {
      let mut cmd = Command::cargo_bin(env!("CARGO_PKG_NAME")).unwrap();
      cmd.arg("--version")
          .assert()
          .success()
          .stdout(predicate::str::contains(env!("CARGO_PKG_VERSION")));
  }
  ```

  **GREEN implementation (src/main.rs):**
  ```rust
  use clap::Parser;

  #[derive(Parser)]
  #[command(name = env!("CARGO_PKG_NAME"))]
  #[command(version = env!("CARGO_PKG_VERSION"))]
  #[command(about = env!("CARGO_PKG_DESCRIPTION"))]
  struct Cli {
      // Add from spec requirements
  }

  fn main() {
      let _cli = Cli::parse();
      // Implementation
  }
  ```

  ## STEP 7: PROPERTY-BASED TESTING

  **Add proptest for robustness:**

  ```rust
  use proptest::prelude::*;

  proptest! {
      #[test]
      fn test_core_type_handles_arbitrary_strings(s in "\\PC*") {
          let instance = CoreType::new(s.clone());
          assert_eq!(instance.name(), s);
      }

      #[test]
      fn test_process_always_appends_suffix(s in "\\PC*") {
          let instance = CoreType::new(s.clone());
          let processed = instance.process();
          assert!(processed.ends_with("_processed"));
      }
  }
  ```

  ## STEP 8: BENCHMARKING

  **From spec, identify performance-critical paths:**

  **benches/benchmarks.rs:**
  ```rust
  use criterion::{black_box, criterion_group, criterion_main, Criterion};
  use ${PROJECT_NAME}::*;

  fn benchmark_core_operation(c: &mut Criterion) {
      c.bench_function("core_operation", |b| {
          b.iter(|| {
              let instance = CoreType::new(black_box("test"));
              instance.process()
          });
      });
  }

  criterion_group!(benches, benchmark_core_operation);
  criterion_main!(benches);
  ```

  **Run benchmarks:**
  ```bash
  cargo bench
  # Save baseline
  cargo bench --save-baseline initial
  ```

  ## STEP 9: DOCUMENTATION

  **Update README with actual usage:**
  ```bash
  # Generate example output
  cargo run -- --help > /tmp/help.txt

  # Update README.md with real examples
  ```

  **Verify documentation accuracy:**
  ```bash
  # Generate deep context
  pmat context --output deep_context.md --format llm-optimized

  # Validate README
  pmat validate-readme \
      --targets README.md \
      --deep-context deep_context.md \
      --fail-on-contradiction
  ```

  **Add rustdoc examples:**
  ```rust
  /// Process the core type
  ///
  /// # Examples
  ///
  /// ```
  /// use ${PROJECT_NAME}::CoreType;
  ///
  /// let instance = CoreType::new("example");
  /// let result = instance.process();
  /// assert_eq!(result, "example_processed");
  /// ```
  pub fn process(&self) -> String {
      format!("{}_processed", self.name)
  }
  ```

  **Run doc tests:**
  ```bash
  cargo test --doc
  ```

  ## STEP 10: MUTATION TESTING

  **Verify test quality with mutation testing:**

  ```bash
  # Install cargo-mutants
  cargo install cargo-mutants

  # Run mutation testing
  cargo mutants --all-features

  # Target: ≥${MIN_MUTATION_SCORE}% mutation score
  ```

  **If mutation score too low:**
  - Identify surviving mutants
  - Add tests to catch mutations
  - Re-run until ≥${MIN_MUTATION_SCORE}%

  ## STEP 11: QUALITY GATES (FINAL VERIFICATION)

  **Run all quality checks:**

  ```bash
  # 1. Linting
  cargo clippy --all-targets --all-features -- -D warnings

  # 2. Formatting
  cargo fmt --all -- --check

  # 3. Tests
  make test-fast

  # 4. Coverage
  make coverage
  # Verify ≥${MIN_COVERAGE}%

  # 5. Mutation testing
  cargo mutants --all-features
  # Verify ≥${MIN_MUTATION_SCORE}%

  # 6. Complexity
  pmat analyze complexity --path src/ --threshold 20
  # All functions ≤20

  # 7. SATD
  grep -r "TODO\|FIXME\|HACK" src/
  # Zero or all linked to issues

  # 8. Documentation
  pmat validate-readme --targets README.md --deep-context deep_context.md

  # 9. Benchmarks
  cargo bench

  # 10. Repo score
  pmat repo-score --path .
  # Target: ≥80/100
  ```

  ## STEP 12: RELEASE PREPARATION

  **Update version in Cargo.toml:**
  ```toml
  [package]
  version = "0.1.0"
  ```

  **Create CHANGELOG.md:**
  ```markdown
  # Changelog

  ## [0.1.0] - $(date +%Y-%m-%d)

  ### Added
  - Initial implementation of [feature from spec]
  - [Feature 2 from spec]
  - Comprehensive test suite (${MIN_COVERAGE}% coverage)
  - Benchmarks for performance tracking

  ### Quality Metrics
  - Test Coverage: [actual]%
  - Mutation Score: [actual]%
  - Clippy Warnings: 0
  - Repo Score: [actual]/100
  ```

  **Tag release:**
  ```bash
  git add .
  git commit -m "chore: Release v0.1.0"
  git tag -a v0.1.0 -m "Release v0.1.0"
  ```

  **Publish (if applicable):**
  ```bash
  # Dry run
  cargo publish --dry-run

  # Actual publish
  cargo publish
  ```

  ## STEP 13: POST-IMPLEMENTATION VALIDATION

  **Verify specification compliance:**

  Go through specification document section by section:
  - [ ] All requirements implemented
  - [ ] All acceptance criteria met
  - [ ] All performance targets achieved
  - [ ] All quality gates pass
  - [ ] Documentation complete and accurate

  **Create compliance report:**

  ```markdown
  # Specification Compliance Report

  **Specification**: ${SPEC_PATH}
  **Implementation**: ${PROJECT_NAME} v0.1.0
  **Date**: $(date +%Y-%m-%d)

  ## Requirements Compliance

  | Requirement | Status | Evidence |
  |-------------|--------|----------|
  | [Req 1] | ✅ PASS | tests/test_req1.rs:45 |
  | [Req 2] | ✅ PASS | tests/test_req2.rs:78 |

  ## Quality Metrics

  - Test Coverage: [actual]% (target: ${MIN_COVERAGE}%)
  - Mutation Score: [actual]% (target: ${MIN_MUTATION_SCORE}%)
  - Clippy Warnings: 0
  - Complexity: Max 15 (target: ≤20)
  - SATD Comments: 0
  - Repo Score: [actual]/100 (target: ≥80)

  ## Performance Benchmarks

  | Operation | Time | Target |
  |-----------|------|--------|
  | [Op 1] | [time] | [target] |

  ## Conclusion

  ✅ All specification requirements met
  ✅ All quality gates pass
  ✅ Ready for production use
  ```

  ## TOYOTA WAY PRINCIPLES APPLIED

  ### Jidoka (Built-in Quality)
  - Pre-commit hooks enforce quality
  - CI pipeline catches issues early
  - Automated testing at every stage

  ### Andon Cord (Stop the Line)
  - Quality gates block bad code
  - Pre-commit hooks prevent regressions
  - Mutation testing ensures test quality

  ### Genchi Genbutsu (Go and See)
  - Benchmarks provide real performance data
  - Coverage reports show actual test coverage
  - Complexity analysis identifies hotspots

  ### Kaizen (Continuous Improvement)
  - Roadmap guides iterative development
  - Refactor phase in every sprint
  - Quality metrics tracked over time

  ### Zero Defects
  - 100% test pass rate
  - Zero clippy warnings
  - Zero regressions (TDG enforcement)

  ## COMMON PATTERNS

  ### Pattern: Feature Implementation
  ```
  1. RED: Write failing test
  2. GREEN: Implement minimal code
  3. REFACTOR: Clean up
  4. VERIFY: Quality gates
  5. DOCUMENT: Add rustdoc + README
  6. BENCHMARK: Add performance test
  ```

  ### Pattern: Bug Fix
  ```
  1. Reproduce bug with failing test
  2. Fix until test passes
  3. Add regression test
  4. Verify no new regressions
  ```

  ### Pattern: Performance Optimization
  ```
  1. Benchmark current performance
  2. Identify bottleneck (profiling)
  3. Optimize
  4. Verify improvement (benchmark comparison)
  5. Ensure no test regressions
  ```

  ## TIPS

  - Keep commits small and atomic
  - Run tests frequently (after every change)
  - Don't skip the RED phase (proves test works)
  - Refactor continuously (don't accumulate debt)
  - Update roadmap as you learn
  - Celebrate milestones (Toyota Way: Kaizen)

  ## ERROR HANDLING

  **If tests won't compile:**
  - Fix compilation errors first
  - Then worry about test failures

  **If tests pass but shouldn't (false GREEN):**
  - Delete implementation, verify test fails (RED)
  - Re-implement correctly

  **If mutation score too low:**
  - Review surviving mutants
  - Add tests for uncovered scenarios
  - Use property-based tests for edge cases

  **If performance targets not met:**
  - Profile to find bottlenecks
  - Optimize hot paths
  - Consider algorithmic improvements
  - Update spec if targets unrealistic

  This systematic approach ensures every specification is implemented with:
  - Full test coverage
  - Verified quality
  - Complete documentation
  - Zero regressions
toyota_way_principles:
  jidoka: automated_quality_gates_at_every_step
  andon_cord: pre_commit_hooks_block_bad_code
  genchi_genbutsu: data_driven_decisions_from_benchmarks
  kaizen: iterative_development_with_roadmap
  zero_defects: 100_percent_test_pass_rate
methodology_integration:
  extreme_tdd:
    - red_phase_first
    - green_phase_minimal
    - refactor_phase_continuous
  spec_driven:
    - roadmap_from_spec
    - compliance_verification
    - acceptance_criteria_tracking
quality_enforcement:
  pre_commit:
    - clippy_zero_warnings
    - fmt_check
    - tdg_no_regressions
  pre_release:
    - coverage_minimum
    - mutation_score_minimum
    - complexity_limits
    - satd_zero
    - readme_validation
scaffolding_templates:
  rust:
    files:
      - Cargo.toml
      - src/lib.rs
      - src/main.rs
      - tests/
      - benches/
      - Makefile
      - .github/workflows/ci.yml
    structure: "standard cargo workspace"
  python:
    files:
      - pyproject.toml
      - src/
      - tests/
      - Makefile
      - .github/workflows/ci.yml
    structure: "modern python with uv"
