H. DeepSeek Harness Integration

Appendix H: DeepSeek Harness Integration — Supercharging Your Self-Improving Repository¶

Reference: This appendix builds on Chapter 2's implementation, showing how DeepSeek Harness (DSH) can be used as a drop-in enhancement to your existing Git-native, CLI-driven workflow.

H.1 Overview: Harness as a Plugin to this Architecture¶

Chapter 2 implementation already establishes: - Stable interface (Make commands) - Validation gates (scripts/validate.sh) - Context management (AGENTS.md, AI_CONTEXT.md) - Git-native workflow (improve → validate → commit)

DeepSeek Harness doesn't replace this architecture—it plugs into it as a more capable AI backend with specialized features:

Your Chapter 2 Component	Harness Enhancement
CLI Assistant (Aider, Claude CLI)	Harness's agent orchestration, tool calling, and session management
Manual context loading	Automatic context assembly from repository files
Single-model execution	Multi-model orchestration (right model for right task)
Linear improvement	Parallel agent execution with validation loops
Basic validation	Validation hooks that can auto-correct failures

H.2 Installation: Harness as a Make Backend¶

Install Harness alongside your existing CLI assistant:

# Install Harness globally
npm install -g @deepseek-ai/dsh

# Or use it via npx (no installation needed)
npx @deepseek-ai/dsh --help

Add Harness support to your existing Makefile (without changing existing commands):

# =============================================================================
# Existing commands (from Chapter 2) - unchanged
# =============================================================================

.PHONY: status validate commit improve-%

# Your existing commands...
status:
    @./scripts/status.sh

validate:
    @./scripts/validate.sh

commit:
    @./scripts/commit.sh

# =============================================================================
# New: Harness-enhanced commands (drop-in replacements)
# =============================================================================

.PHONY: harness-%

## harness-improve-% — Use Harness for AI improvements with model selection
harness-improve-%:
    @./scripts/harness-improve.sh "$*"

## harness-validate — Run Harness validation with auto-fix
harness-validate:
    @./scripts/harness-validate.sh

## harness-evolve — Full self-improvement loop with Harness
harness-evolve:
    @./scripts/harness-evolve.sh

## harness-cost — Show Harness token usage and cost
harness-cost:
    @dsh cost --period=day

The key insight: Your existing make improve-docs still works. make harness-improve-docs gives you enhanced capabilities. You can choose which to use, or gradually migrate.

H.3 Harness Integration Scripts¶

H.3.1 `scripts/harness-improve.sh` — Intelligent Improvement with Model Selection¶

#!/bin/bash
# harness-improve.sh — Use DeepSeek Harness for AI improvements
# Usage: ./harness-improve.sh [target] [--model=<tier>]

set -euo pipefail

TARGET="${1:-all}"
MODEL_TIER="${2:-editor}"  # editor | architect | reasoning | sovereign

# Load context from your repository's Chapter 2 files
CONTEXT_FILES=(
    "AGENTS.md"
    "AI_CONTEXT.md"
    "docs/rules/"
    "docs/context/"
)

# Build the session command
SESSION_CMD="dsh session"

# Add context files
for file in "${CONTEXT_FILES[@]}"; do
    if [ -f "$file" ]; then
        SESSION_CMD="$SESSION_CMD --read $file"
    elif [ -d "$file" ]; then
        SESSION_CMD="$SESSION_CMD --read-dir $file"
    fi
done

# Model selection based on your Chapter 2 framework
case $MODEL_TIER in
    editor)
        # Fast, cheap model for routine work
        SESSION_CMD="$SESSION_CMD --provider editor"
        ;;
    architect)
        # Complex reasoning for system design
        SESSION_CMD="$SESSION_CMD --provider architect"
        ;;
    reasoning)
        # Step-by-step reasoning for planning
        SESSION_CMD="$SESSION_CMD --provider reasoning"
        ;;
    sovereign)
        # Local model for sensitive data
        SESSION_CMD="$SESSION_CMD --provider sovereign"
        ;;
    *)
        SESSION_CMD="$SESSION_CMD --provider editor"
        ;;
esac

# Add the improvement prompt (using your Chapter 2 prompt structure)
SESSION_CMD="$SESSION_CMD --prompt \"Improve the $TARGET following AGENTS.md rules and AI_CONTEXT.md patterns. Run validation and fix any issues.\""

# Execute the session
echo "🚀 Running Harness improvement session..."
echo "   Target: $TARGET"
echo "   Model tier: $MODEL_TIER"
echo "   Context: ${CONTEXT_FILES[*]}"
echo ""

eval $SESSION_CMD

# Auto-validate after improvement
echo ""
echo "🔍 Validating improvements..."
./scripts/validate.sh

# If validation fails, use Harness to auto-fix
if [ $? -ne 0 ]; then
    echo "❌ Validation failed. Running Harness auto-fix..."
    dsh session --provider editor \
        --read AGENTS.md \
        --read AI_CONTEXT.md \
        --prompt "Fix the validation failures in the $TARGET based on the error output. Apply the fixes and re-validate."

    ./scripts/validate.sh
fi

echo "✅ Improvement complete"

H.3.2 `scripts/harness-validate.sh` — Intelligent Validation with Harness¶

#!/bin/bash
# harness-validate.sh — Use Harness for enhanced validation with auto-fix

set -euo pipefail

echo "🔍 Running Harness-enhanced validation..."

# Run your existing validation
./scripts/validate.sh
VALIDATION_EXIT=$?

if [ $VALIDATION_EXIT -eq 0 ]; then
    echo "✅ Validation passed!"
    exit 0
fi

echo "❌ Validation failed. Harness will analyze and fix..."
echo ""

# Harness analyzes the validation failure
dsh session \
    --provider editor \
    --read AGENTS.md \
    --read AI_CONTEXT.md \
    --read scripts/validate.sh \
    --prompt "The validation script failed. Analyze the errors, identify the root cause, and generate a fix. Apply the fix to the repository."

# Re-run validation
echo ""
echo "🔍 Re-running validation..."
./scripts/validate.sh

if [ $? -eq 0 ]; then
    echo "✅ Validation passed after Harness fix!"
    echo "💡 To commit these changes: make commit"
else
    echo "❌ Validation still failing. Manual intervention required."
    echo "   Check: ./scripts/validate.sh"
    exit 1
fi

H.3.3 `scripts/harness-evolve.sh` — Full Self-Improvement Loop¶

#!/bin/bash
# harness-evolve.sh — Complete self-improvement loop with Harness
# This implements Chapter 2's "Self-Improving Repository Workflow" with Harness

set -euo pipefail

echo "🔄 Starting Harness self-improvement loop..."
echo ""

# Step 1: Assess current state
echo "📊 Step 1: Assessing repository state..."
./scripts/status.sh

# Step 2: Identify improvements using Harness
echo ""
echo "🤖 Step 2: Harness identifies improvement opportunities..."
dsh session \
    --provider reasoning \
    --read AGENTS.md \
    --read AI_CONTEXT.md \
    --read scripts/ \
    --prompt "Analyze this repository. Identify 3-5 improvements that would:
    1. Make the repository more self-improving
    2. Improve validation coverage
    3. Enhance context documentation
    4. Optimize the workflow

    Prioritize by impact. Output specific, actionable improvements."

# Step 3: Apply improvements
echo ""
echo "🔧 Step 3: Applying improvements..."
dsh session \
    --provider architect \
    --read AGENTS.md \
    --read AI_CONTEXT.md \
    --read scripts/ \
    --prompt "Apply the top-priority improvement identified in the previous step. Follow AGENTS.md rules and AI_CONTEXT.md patterns."

# Step 4: Validate
echo ""
echo "🔍 Step 4: Validating improvements..."
./scripts/harness-validate.sh

# Step 5: Commit if all validations pass
echo ""
echo "📝 Step 5: Committing improvements..."
make commit

echo ""
echo "✅ Self-improvement loop complete!"
echo "🔁 Run again: make harness-evolve"

H.4 Harness-Specific Configuration¶

H.4.1 `.dsh/config/providers.yml` — Model Selection from Chapter 2¶

# DeepSeek Harness provider configuration
# Maps to Chapter 2's Model Selection Framework

providers:
  # Chapter 2: "Editor Tier" — Fast, efficient for routine work
  - id: editor
    type: openai-completions
    api: https://api.deepseek.com/v1
    model: deepseek-v4-flash
    cost_per_1k_input: 0.0002
    cost_per_1k_output: 0.0006
    max_tokens: 4096
    description: "Fast, cheap model for routine tasks like documentation, simple scripts, boilerplate"

  # Chapter 2: "Architect Tier" — Complex reasoning for system design
  - id: architect
    type: openai-completions
    api: https://api.deepseek.com/v1
    model: deepseek-v4-reasoning
    cost_per_1k_input: 0.0012
    cost_per_1k_output: 0.0036
    max_tokens: 8192
    description: "Complex reasoning model for system design, architecture decisions, multi-step planning"

  # Chapter 2: "Reasoning Tier" — Step-by-step planning
  - id: reasoning
    type: openai-completions
    api: https://api.deepseek.com/v1
    model: deepseek-v4-planning
    cost_per_1k_input: 0.0008
    cost_per_1k_output: 0.0024
    max_tokens: 16384
    description: "Step-by-step reasoning for complex planning, problem decomposition, debugging"

  # Chapter 2: "Sovereign Tier" — Sensitive data (local)
  - id: sovereign
    type: local
    command: ollama run deepseek-coder:14b
    cost_per_1k_input: 0
    cost_per_1k_output: 0
    max_tokens: 8192
    description: "Local model for sensitive data, no cloud API costs, data never leaves your machine"

H.4.2 `.dsh/config/tools.yml` — Your Chapter 2 Validation as Harness Tools¶

# DeepSeek Harness tool definitions
# Maps to Chapter 2's Validation Layer

tools:
  # Chapter 2: "Validation Gate" as a Harness tool
  - id: validate
    type: command
    command: ./scripts/validate.sh
    description: "Run the repository's validation suite"
    input_schema:
      type: object
      properties:
        target:
          type: string
          description: "Specific file or component to validate"
    output_schema:
      type: object
      properties:
        passed:
          type: boolean
        failures:
          type: array
          items:
            type: string

  # Chapter 2: "Status Check" as a Harness tool  
  - id: status
    type: command
    command: ./scripts/status.sh
    description: "Show repository status and next actions"

  # Chapter 2: "Context Assembly" as a Harness tool
  - id: load-context
    type: file-reader
    files:
      - AGENTS.md
      - AI_CONTEXT.md
      - docs/rules/
      - docs/context/
    description: "Load repository context from Chapter 2 files"

  # Chapter 2: "Improvement" as a Harness tool
  - id: improve
    type: agent
    prompt_template: |
      Improve the following component following AGENTS.md rules and AI_CONTEXT.md patterns.

      Component: {{target}}

      Rules to follow:
      {{AGENTS.md}}

      Context:
      {{AI_CONTEXT.md}}

      Steps:
      1. Analyze the current state
      2. Apply improvements
      3. Validate the changes
      4. Report the result
    description: "AI-assisted improvement following repository rules"

H.4.3 `.dsh/config/profiles.yml` — Pre-configured Workflows¶

# Harness profiles — pre-configured workflows that map to your Make commands

profiles:
  # Chapter 2: "make improve-docs" as a Harness profile
  - id: improve-docs
    description: "Improve documentation following repository standards"
    model: editor
    tools:
      - load-context
      - improve
      - validate
    prompt: |
      Improve the documentation in this repository.

      Focus areas:
      1. Accuracy — ensure technical details are correct
      2. Completeness — cover all major components
      3. Clarity — make it understandable for new team members
      4. Consistency — match existing documentation style

      Follow AGENTS.md rules and AI_CONTEXT.md patterns.
      Run validation after making changes.

  # Chapter 2: "make improve-code" as a Harness profile
  - id: improve-code
    description: "Improve code quality following repository standards"
    model: architect
    tools:
      - load-context
      - improve
      - validate
    prompt: |
      Improve the code quality in this repository.

      Focus areas:
      1. Refactor for clarity and maintainability
      2. Add missing type hints and documentation
      3. Improve test coverage
      4. Optimize performance where beneficial

      Follow AGENTS.md rules and AI_CONTEXT.md patterns.
      Run validation after making changes.

  # Chapter 2: "make improve-infra" as a Harness profile
  - id: improve-infra
    description: "Improve Infrastructure as Code following repository standards"
    model: reasoning
    tools:
      - load-context
      - improve
      - validate
    prompt: |
      Improve the Infrastructure as Code in this repository.

      Focus areas:
      1. Security — ensure least-privilege, encryption, proper network controls
      2. Compliance — meet organizational and regulatory requirements
      3. Cost — optimize resource usage
      4. Maintainability — follow module patterns and naming conventions

      Follow AGENTS.md rules and AI_CONTEXT.md patterns.
      Run validation after making changes.

  # Chapter 2: "Self-Improvement Loop" as a Harness profile
  - id: evolve
    description: "Full self-improvement loop"
    model: reasoning
    tools:
      - status
      - load-context
      - improve
      - validate
    prompt: |
      Run the full self-improvement loop:
      1. Assess current repository state
      2. Identify 3-5 improvement opportunities
      3. Apply improvements
      4. Validate all changes
      5. Prepare for commit

      Follow AGENTS.md rules and AI_CONTEXT.md patterns.

H.5 Enhanced Makefile with Harness¶

# =============================================================================
# Enhanced Makefile — existing commands + Harness integration
# =============================================================================

# =============================================================================
# Existing commands (Chapter 2 foundation) — UNCHANGED
# =============================================================================

.PHONY: status sync log diff diff-staged diff-main last branches \
        commit unstage unstage-all release \
        validate improve-% check

## status — short git status + suggested next action
status:
    @./scripts/status.sh

## validate — run validation gates
validate:
    @./scripts/validate.sh

## improve-% — AI-assisted improvement (existing backend)
improve-%:
    @./scripts/improve.sh "$*"

## commit — commit staged changes with validation
commit: check
    @m="$(m)" ./scripts/commit.sh

## check — validation gate before commit (Chapter 2 pattern)
check:
    @./scripts/validate.sh

# =============================================================================
# New: Harness-enhanced commands (drop-in replacements)
# =============================================================================

.PHONY: harness-%

## harness-validate — Harness-enhanced validation with auto-fix
harness-validate:
    @./scripts/harness-validate.sh

## harness-improve-% — Harness improvement with model selection
harness-improve-%:
    @./scripts/harness-improve.sh "$*" "$(MODEL)"

## harness-evolve — Full self-improvement loop with Harness
harness-evolve:
    @./scripts/harness-evolve.sh

## harness-cost — Show Harness token usage and cost
harness-cost:
    @dsh cost --period=day

## harness-status — Show Harness session status
harness-status:
    @dsh status

## harness-logs — Show Harness session logs
harness-logs:
    @dsh logs --tail=50

# =============================================================================
# Convenience aliases for common tasks
# =============================================================================

## improve — Alias for improve-docs (keeps the old command)
improve: improve-docs

## h-improve — Alias for harness-improve with default editor model
h-improve: harness-improve-docs

## h-improve-arch — Harness improvement with architect model
h-improve-arch: MODEL=architect harness-improve-docs

## h-improve-reason — Harness improvement with reasoning model
h-improve-reason: MODEL=reasoning harness-improve-docs

## h-evolve — Quick access to self-improvement loop
h-evolve: harness-evolve

## help — Show all available commands
help:
    @echo "📋 Available commands:"
    @echo ""
    @echo "Foundation (Chapter 2):"
    @echo "  make status               — Show repository state"
    @echo "  make validate             — Run validation gates"
    @echo "  make improve-docs         — Improve documentation (existing)"
    @echo "  make commit               — Commit with validation"
    @echo ""
    @echo "Harness Enhanced:"
    @echo "  make harness-improve-docs — Harness improvement (editor model)"
    @echo "  make h-improve-arch       — Harness improvement (architect model)"
    @echo "  make h-improve-reason     — Harness improvement (reasoning model)"
    @echo "  make harness-validate     — Validate with auto-fix"
    @echo "  make harness-evolve       — Full self-improvement loop"
    @echo "  make harness-cost         — Show Harness usage and cost"
    @echo ""
    @echo "Examples:"
    @echo "  make h-improve-arch TARGET=infra  # Improve infrastructure with architect model"
    @echo "  make h-evolve                     # Run full self-improvement loop"

H.6 Chapter 2 → Harness Mapping Summary¶

Chapter 2 Concept	Chapter 2 Implementation	Harness Enhancement
Repository as Intelligence	`AGENTS.md`, `AI_CONTEXT.md`	Harness reads these automatically and uses them as system context
Command Surface Contract	`make status`, `make validate`, `make commit`	Harness profiles map to these commands; additional `harness-*` variants
Validation Layer	`scripts/validate.sh`	Harness tools call validation; can auto-fix failures
Self-Improving Workflow	improve → validate → commit loop	Harness `evolve` profile adds model selection and parallel execution
Durable Abstraction	Make interface, pluggable scripts	Harness can be used as a pluggable backend (or alongside existing)
Token Economics	Manual cost awareness	Harness provides built-in cost tracking, provider selection, and optimization
Model Selection	Manual tier selection	Harness profiles encode model selection; `--provider` flag for override

H.7 Getting Started with Harness¶

Step 1: Install Harness (15 minutes)¶

# Install via npm
npm install -g @deepseek-ai/dsh

# Verify installation
dsh --version

# Set up API keys (if using cloud models)
export DEEPSEEK_API_KEY="your-api-key"

# Or use local models
export DSH_LOCAL_MODEL="ollama run deepseek-coder:14b"

Step 2: Initialize Harness Configuration (10 minutes)¶

# Create Harness configuration directory
mkdir -p .dsh/config

# Copy provider configuration
cp appendix-h/providers.yml .dsh/config/

# Copy tool definitions
cp appendix-h/tools.yml .dsh/config/

# Copy profiles
cp appendix-h/profiles.yml .dsh/config/

Step 3: Add Harness Integration Scripts (15 minutes)¶

# Copy integration scripts
cp appendix-h/harness-improve.sh scripts/
cp appendix-h/harness-validate.sh scripts/
cp appendix-h/harness-evolve.sh scripts/

# Make them executable
chmod +x scripts/harness-*.sh

# Update your Makefile (add the Harness section)
cat appendix-h/enhanced-makefile.mk >> Makefile

Step 4: Test the Integration (10 minutes)¶

# Test Harness improvement
make h-improve docs

# Test Harness validation
make harness-validate

# Test full self-improvement loop
make h-evolve

# Check Harness usage and cost
make harness-cost

H.8 When to Use Harness vs. Your Existing Workflow¶

Scenario	Use Your Existing Workflow	Use Harness
Simple documentation updates	✅ `make improve-docs`	⬜ `make h-improve docs`
Complex system design	⬜	✅ `make h-improve-arch TARGET=system`
Sensitive data (NV1/gov)	⬜	✅ `make h-improve sovereign`
Routine code formatting	✅ `make improve-code`	⬜
Multi-step planning	⬜	✅ `make h-improve-reason TARGET=plan`
Cost-sensitive tasks	✅ (single model)	⬜
Tasks requiring multiple models	⬜	✅ Harness orchestrates
Self-improvement loop	✅ Manual	✅ `make h-evolve` (automated)

The key insight: Harness is an addition to your existing workflow, not a replacement. You choose the right tool for the right task.

H.9 Summary: Harness in Your Chapter 2 Architecture¶

DeepSeek Harness integrates with your Chapter 2 implementation by:

Respecting your repository structure — Reads AGENTS.md, AI_CONTEXT.md, validation scripts
Using your command surface — Harness commands are accessible via make harness-* targets
Enhancing your validation — Auto-fixes validation failures
Adding model orchestration — Right model for the right task (Chapter 2's framework)
Providing cost governance — Built-in cost tracking and optimization
Enabling parallel agents — Harness can run multiple agents in parallel
Improving the self-improvement loop — make h-evolve automates the full cycle

Your Chapter 2 repository remains the permanent foundation. Harness is a transient reader that can be swapped out without losing structure.

The result: You get the best of both worlds — the durable, Git-native workflow from Chapter 2, enhanced by Harness's advanced AI capabilities when you need them.

This appendix demonstrates how DeepSeek Harness enhances your Chapter 2 implementation without changing its core principles. The repository remains the source of truth; Harness is a powerful tool that reads that truth and acts on it.