Context-Sync

A desktop application for managing GitHub-versioned context repositories for spec-driven software development.

Download

Latest Release: v0.1.0

Installation

Platform	Download	Notes
Windows	Setup.exe	Squirrel installer with auto-updates
macOS	.zip	Extract and drag to Applications
Linux (Debian/Ubuntu)	.deb	`sudo dpkg -i context-sync*.deb`
Linux (Fedora/RHEL)	.rpm	`sudo rpm -i context-sync*.rpm`

Note: Code signing for Windows and macOS coming soon. You may need to allow the app in your security settings.

Project Status

MVP Development - Phase 7 Complete ✅

Completed Phases

Phase 1-2: Foundation ✅

✅ Electron Forge + Vite + TypeScript setup
✅ Vue 3 + Pinia + Tailwind CSS configuration
✅ IPC bridge between main and renderer processes
✅ Context repository structure
✅ JSON Schemas for all 6 entity types
✅ Validation pipeline with AJV
✅ Sample YAML entities for testing

Phase 3: Core UI ✅

✅ YAML editor component with CodeMirror
✅ Live schema validation in editor
✅ File save/load operations
✅ Enhanced ContextTree with filtering
✅ Impact panel with real-time analysis

Phase 4: Prompt Generation ✅

✅ Handlebars template system
✅ Prompt generation pipeline
✅ Prompt modal with copy-to-clipboard
✅ Template-based prompt rendering

Phase 5: Graph Visualization ✅

✅ Cytoscape.js integration
✅ Interactive dependency graph
✅ Node coloring by entity type
✅ Path finding between nodes
✅ Zoom, pan, and search functionality
✅ Click to open entity in editor

Phase 6: Git Integration ✅

✅ Git status tracking (via simple-git)
✅ Diff viewer for changed files
✅ Commit UI with smart templates
✅ Branch creation and switching
✅ PR creation via GitHub CLI
✅ Impact analysis in commit messages

Phase 7: CI/CD ✅

✅ GitHub Actions workflow for validation
✅ Impact analysis on pull requests
✅ PR comment bot with reports
✅ Merge protection documentation
✅ Complete CI/CD pipeline

Phase 8: Polish & Docs ✅

✅ Error handling (network, file I/O)
✅ Loading states and spinners
✅ Keyboard shortcuts (Ctrl+N for entity creation)
✅ User guide (README)

Phase 9: Context Building & Generation ✅

✅ Multi-step wizard modal for entity creation
✅ Smart suggestions (domain, relationships, ID generation)
✅ Template library with 7 pre-built entity patterns
✅ AI integration (Ollama and Azure OpenAI support)
✅ Secure credential storage with OS-level encryption
✅ Keyboard shortcuts (Ctrl+N for quick create)
✅ Auto-commit and feature branch creation
✅ Bulk entity creation mode

Current Phase

All MVP phases complete! The application now includes:

AI-Assisted Entity Creation: Generate entities from natural language with Ollama or Azure OpenAI
Intelligent Context Building: Smart suggestions, templates, and relationship inference
Material 3 Design System: Consistent, modern UI with Intel brand colors

Prerequisites

Node.js: 22+ (LTS)
pnpm: 10+ (installed via corepack)
Git: 2.33+
PowerShell: 7+ (Windows)

Quick Start

1. Clone and Setup

# Clone the repository
git clone https://github.com/lukeus/my-context-kit.git
cd my-context-kit

# Enable pnpm (if not already enabled)
corepack enable
corepack prepare pnpm@latest --activate

2. Install Dependencies

# Install app dependencies
cd app
pnpm install

# Install context-repo dependencies (if needed)
cd ../context-repo
pnpm install

# Return to app directory
cd ../app

3. Run the Application

# Start the Electron app in development mode
pnpm start

The app will launch and open a window where you can:

Browse and edit YAML entities in the context repository
Create new entities with AI assistance using natural language
View dependency graphs between features, stories, specs, and tasks
Validate entity schemas
Generate AI-ready prompts
Commit changes with Git integration

4. Validate Context Repository (Optional)

# From project root
cd context-repo
pnpm validate

Context Kit Service

NEW: Integrated Python FastAPI service for AI-powered context operations.

Quick Setup

# From project root
pnpm service:setup        # Setup Python environment with uv
pnpm service:start        # Start the service (or let Electron auto-start it)
pnpm service:health       # Check if service is running

Service Commands

pnpm service:setup        # Install Python dependencies
pnpm service:dev          # Start with hot reload
pnpm service:test         # Run pytest tests
pnpm service:lint         # Check code quality
pnpm service:typecheck    # Run mypy type checking
pnpm service:clean        # Clean virtual environment

Features

Context Inspection: Analyze repository structure and entity relationships
Spec Generation: AI-powered technical specification generation
Promptification: Convert specs into agent-ready prompts
Code Generation: Generate implementation artifacts from specifications
Spec Logging: All operations logged to .context-kit/spec-log/

Integration

The Context Kit service is automatically started by Electron and managed throughout the application lifecycle:

Auto-Start: Service spawns when Electron app launches
Health Monitoring: 30-second health checks
Auto-Cleanup: Virtual environment removed on app quit
IPC Bridge: Seamless communication between Vue UI and Python service

See context-kit-service/README.md for detailed documentation.

Spec Kit Workflow

Additional Prerequisites

Access to the github/spec-kit release artifacts (GitHub credentials or token if releases are private)
Outbound HTTPS connectivity from the desktop where Context-Sync runs
context-repo/.context committed to Git so cached releases and telemetry stay traceable

Fetch & Cache Lifecycle

Use Fetch Spec Kit inside the Speckit Workflow (or run pnpm exec node .context/pipelines/speckit-fetch.mjs --repoPath %CD% from context-repo/).
Successful fetches update .context/state/speckit-fetch.json with provenance and hydrate .context/speckit-cache/<tag>/ with markdown previews and templates.
The Speckit store treats the cache as stale when fetchedAt is older than seven days. Stale caches surface warnings in the UI and block generation until a refresh (or an explicit override from the command palette).

Policy: Keep Spec Kit caches younger than seven days to guarantee template freshness. The UI prompts for refresh and will refuse to run generation workflows until the cache is renewed.

Automated Pipeline Verification

After entities are generated from Spec Kit markdown, Context-Sync automatically runs validate, build-graph, impact, and generate in order.
Each stage’s status, errors, and generated file paths appear in the Pipeline Status panel, with quick links back to both the YAML entity and originating Spec Kit preview.
The workflow reuses cached fetch data; rerunning the pipelines after fixes simply retries the chain without requiring another fetch unless the cache is stale.

Project Structure

my-context-kit/
├── app/                          # Electron desktop application
│   ├── src/
│   │   ├── main/                 # Electron main process
│   │   │   ├── index.ts          # Main entry, BrowserWindow, IPC handlers
│   │   │   └── preload.ts        # Context bridge for renderer IPC
│   │   └── renderer/             # Vue 3 frontend
│   │       ├── main.ts           # Vue app initialization
│   │       ├── App.vue           # Root component
│   │       ├── components/       # Vue components
│   │       ├── stores/           # Pinia stores
│   │       └── styles/           # Tailwind CSS
│   ├── forge.config.ts           # Electron Forge configuration
│   ├── vite.*.config.ts          # Vite configurations
│   └── package.json
│
├── context-repo/                 # Git-versioned source of truth
│   ├── .context/
│   │   ├── schemas/              # JSON Schemas for validation
│   │   ├── rules/                # Consistency rules
│   │   ├── templates/            # Handlebars templates
│   │   └── pipelines/            # Node.js scripts
│   │       └── validate.mjs      # Schema validation
│   ├── contexts/                 # YAML entity storage
│   │   ├── features/
│   │   ├── userstories/
│   │   ├── specs/
│   │   ├── tasks/
│   │   ├── services/
│   │   └── packages/
│   └── generated/                # Auto-generated artifacts
│       ├── prompts/
│       └── docs/
│
├── docs/                         # Documentation
│   └── spec.md                   # Technical specification
├── WARP.md                       # Build guide
└── README.md                     # This file

Technology Stack

Layer	Technology	Purpose
Desktop Framework	Electron Forge 7	Cross-platform packaging
Frontend	Vue 3 (Composition API)	Reactive UI
State Management	Pinia	Centralized state
Styling	Tailwind CSS	Utility-first CSS
Build Tool	Vite 5	Fast bundling
Type Safety	TypeScript (strict)	Static typing
Schema Validation	AJV	YAML validation
Templating	Handlebars	Prompt generation
Graph Visualization	Cytoscape.js	Dependency graphs
Git Integration	simple-git	Version control
Package Manager	pnpm (exclusive)	Fast dependencies

Development Commands

App Development

cd app

pnpm start          # Start Electron app in dev mode
pnpm build          # Build for production
pnpm package        # Package as executable
pnpm lint           # Lint TypeScript/Vue files
pnpm format         # Auto-fix linting issues
pnpm typecheck      # TypeScript type checking

Quality & Verification Scripts

# From repository root
pnpm verify:tokens  # Verify Material 3 semantic token usage
pnpm scan:time      # Scan for duplicate time formatting helpers

These scripts help maintain code quality by:

verify:tokens: Ensures components use semantic design tokens (e.g., bg-surface) instead of raw Tailwind color classes (e.g., bg-blue-500)
scan:time: Detects duplicate time/duration formatting functions to ensure centralization

Context Repository

cd context-repo

node .context/pipelines/validate.mjs       # Validate all YAML entities
node .context/pipelines/build-graph.mjs    # Build dependency graph
node .context/pipelines/impact.mjs FEAT-001 # Run impact analysis
node .context/pipelines/generate.mjs FEAT-001 # Generate prompts

Entity Types

The context repository supports 6 entity types:

Feature (FEAT-###) - High-level capabilities
User Story (US-###) - User-centric functionality
Spec (SPEC-###) - Technical specifications
Task (T-###) - Implementation tasks
Service - Backend/infrastructure services
Package - Software packages/libraries

All entities are stored as YAML files and validated against JSON Schemas.

Validation

The validation pipeline checks:

✅ YAML syntax correctness
✅ Schema compliance (required fields, types, patterns)
✅ Cross-reference integrity (no dangling references)
✅ ID format consistency

Example validation output:

{
  "ok": true,
  "message": "All validations passed",
  "stats": {
    "totalEntities": 9,
    "byType": {
      "feature": 1,
      "userstory": 2,
      "spec": 1,
      "task": 3,
      "service": 1,
      "package": 1
    }
  }
}

Configuration

Module Resolution

All code uses Bundler module resolution:

Extensionless imports (no .js suffix)
Path aliases: @/* (renderer), ~main/* (main)
Unified Vite bundling for main, preload, and renderer

TypeScript

{
  "compilerOptions": {
    "moduleResolution": "Bundler",
    "module": "ESNext",
    "target": "ES2022",
    "strict": true
  }
}

Best Practices

Code Quality

✅ Use TypeScript with strict typing
✅ Avoid shortcuts - prioritize correctness
✅ Break large tasks into smaller pieces
✅ Write self-documenting code

Workflow

✅ Run pnpm lint after building
✅ Fix all lint issues before deploying
✅ Never deploy without confirmation
✅ Never commit without explicit request

Security

✅ No hardcoded secrets
✅ Use environment variables
✅ Context isolation enabled (contextIsolation: true)
✅ No node integration in renderer

Material 3 Design Tokens & Verification Scripts

Semantic Token Compliance: The app enforces Material 3 design token usage across all components. Raw Tailwind color classes (e.g., bg-blue-500, text-gray-700) are prohibited except for documented exceptions.

Verification Scripts:

# Scan for raw color violations (target: ≤5 exceptions)
pnpm --filter context-sync exec tsx scripts/verify-design-tokens.ts

# Check for duplicate time formatting helpers
pnpm --filter context-sync exec tsx scripts/scan-duplicate-time-helpers.ts

# Verify error normalization coverage
pnpm --filter context-sync exec tsx scripts/verify-error-telemetry.ts

Semantic Token Categories:

primary, secondary, tertiary - Brand hierarchy
error, warning, success, info - Status semantics
surface, outline - Backgrounds and borders
*-container, on-*-container - Container pairs

Acceptance Criteria:

≥95% semantic token coverage (current: 84% with 68 documented exceptions)
All exceptions documented with rationale (data visualization, chart colors)
CI gates fail on undocumented raw color violations

See app/tailwind.config.ts for full token palette and specs/001-code-cleanup/research.md for exception documentation.

Troubleshooting

Common Issues

Issue: pnpm: command not found

corepack enable
corepack prepare pnpm@latest --activate

Issue: Vite plugin missing

pnpm add -D @electron-forge/plugin-vite

Issue: Tailwind not applying

Check tailwind.config.ts content glob includes src/renderer/**/*.vue
Verify @tailwind directives in CSS

Issue: Validation fails

cd context-repo
pnpm validate
# Review error output for schema/cross-reference issues

Features

✅ Implemented

AI Assistant (Enhanced)

Streaming Responses: Real-time token-by-token AI responses with progress indicators
Configurable Prompts: Customize system prompts, quick actions, and example questions via UI
Token Probability Viewer: Visualize AI confidence levels with color-coded token probabilities (Azure OpenAI)
Smart Edit Suggestions: AI proposes YAML edits with validation before application
Multi-Provider Support: Ollama (local) and Azure OpenAI with automatic capability detection
Secure Credentials: Encrypted API key storage using OS-level security (Windows Credential Manager)
Conversation History: Context-aware multi-turn conversations with clear, chat-like interface

Editor & Validation

Auto-Refresh YAML Editor: Automatically reloads files after AI edits are applied
Enhanced Diff Viewer: Side-by-side comparison with syntax highlighting and color-coded changes
Pre-Edit Validation: YAML syntax validation before applying AI-generated changes
Live Schema Validation: Real-time error detection with inline warnings

Core Features

AI-Assisted Entity Creation: Generate entities from natural language
Smart Context Builder: 4-step wizard with templates, suggestions, and validation
Context Management: Browse, edit, and validate YAML entities
Dependency Graph: Visual representation with interactive entity relationships
Impact Analysis: See what changes affect related entities
Prompt Generation: Create AI-ready context for coding agents
Git Workflow: Commit, branch, create PRs from within the app
CI/CD: Automated validation and impact analysis on PRs
Material 3 Design: Modern, consistent UI with Intel brand colors
Keyboard Shortcuts: Ctrl+N for quick create, Ctrl+S for save, Ctrl+Enter to send AI queries

🎯 Key Features

Context Building (Phase 9):

Multi-step wizard for creating features, user stories, specs, and tasks
AI generation from natural language prompts ("Create a feature for user authentication with OAuth")
Smart domain suggestions based on keywords and existing patterns
Relationship suggestions with confidence levels (high ✨, medium, low)
Template library: CRUD operations, API integration, UI components, bug fixes
Auto-commit with smart commit messages and feature branch creation
Bulk creation mode for related entities
Real-time ID conflict detection and validation

Contributing

Follow the existing architecture
Use pnpm exclusively
Write TypeScript with strict typing
Test locally with pnpm start
Validate changes with pnpm lint and pnpm typecheck

Documentation

WARP.md - Complete build guide
docs/spec.md - Technical specification
docs/phase6-git-workflow-completion.md - Git integration
docs/phase7-cicd-documentation.md - CI/CD pipeline
docs/merge-protection-setup.md - Branch protection guide
.github/copilot-instructions.md - AI assistant guidelines

License

MIT

Author

Luke Adams (@lukeu)

Status: MVP Phase 7 Complete | Version: 0.7.0 | Last Updated: 2025-10-24

Name		Name	Last commit message	Last commit date
Latest commit History 215 Commits
.github		.github
.specify		.specify
app		app
context-kit-service		context-kit-service
context-repo		context-repo
docs		docs
scripts		scripts
specs		specs
.dockerignore		.dockerignore
.eslintignore		.eslintignore
.gitignore		.gitignore
.prettierignore		.prettierignore
CHANGELOG.md		CHANGELOG.md
README.md		README.md
RELEASING.md		RELEASING.md
SECURITY.md		SECURITY.md
WARP.md		WARP.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml

Lukeus/my-context-kit

Folders and files

Latest commit

History

Repository files navigation

Context-Sync

Download

Installation

Project Status

Completed Phases

Phase 1-2: Foundation ✅

Phase 3: Core UI ✅

Phase 4: Prompt Generation ✅

Phase 5: Graph Visualization ✅

Phase 6: Git Integration ✅

Phase 7: CI/CD ✅

Phase 8: Polish & Docs ✅

Phase 9: Context Building & Generation ✅

Current Phase

Prerequisites

Quick Start

1. Clone and Setup

2. Install Dependencies

3. Run the Application

4. Validate Context Repository (Optional)

Context Kit Service

Quick Setup

Service Commands

Features

Integration

Spec Kit Workflow

Additional Prerequisites

Fetch & Cache Lifecycle

Automated Pipeline Verification

Project Structure

Technology Stack

Development Commands

App Development

Quality & Verification Scripts

Context Repository

Entity Types

Validation

Configuration

Module Resolution

TypeScript

Best Practices

Code Quality

Workflow

Security

Material 3 Design Tokens & Verification Scripts

Troubleshooting

Common Issues

Features

✅ Implemented

AI Assistant (Enhanced)

Editor & Validation

Core Features

🎯 Key Features

Contributing

Documentation

License

Author

About

Resources

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 2

Packages 0

Uh oh!

Contributors 4

Uh oh!

Languages

Packages