v1.1.1

What's Changed

• [release] v1.1.0 by @vinilana in #67
• add: dotcontext image by @vinilana in #68
• [fix] Harden hook output contracts by @vinilana in #69

Full Changelog: v1.1.0...v1.1.1

v1.1.0

What's Changed

• release: 1.0.0 - hexagonal harness refactor + Claude/Codex hooks & Pi.dev support by @vinilana in #63
• [fix] reduce hook workflow noise by @vinilana in #64
• [chore] enhance MCP install command with hook recommendations by @vinilana in #65
• [chore] Change interactive CLI prompts and integrations by @vinilana in #66

Full Changelog: v1.0.0...v1.1.0

v1.0.0

[1.0.0]

This is a structural refactor of dotcontext ahead of 1.0.0. It replaces the monolithic src/services / src/workflow layout with a hexagonal harness core and thin adapters for CLI, MCP, and host hooks.

New: Claude Code hooks, Codex CLI hooks, and Pi.dev

Dotcontext is no longer MCP-only. 1.0.0 introduces first-class support for three major agent hosts — the same harness runtime, wired into each tool's native lifecycle:

Host	How it connects	What you get
Claude Code	Shell hooks via settings.json	Context bootstrap on session start, durable traces after Write/Edit/Bash, PREVC workflow reminders on stop
Codex CLI	Shell hooks via hooks.json or inline TOML	Same harness actions as Claude Code; JSON or TOML install formats
Pi.dev	In-process npm extension (@dotcontext/pi)	Lifecycle hooks without shell dispatch — bootstrap, tracing, and workflow guidance inside Pi

One runtime, three surfaces. Hooks and Pi call the same harness actions as MCP (context check, harness appendTrace, workflow-guide). No duplicated PREVC logic per host.

Quick start:

# Install hooks (interactive — detects installed hosts)
npx -y @dotcontext/cli@latest hook install

# Or target a host explicitly
npx -y @dotcontext/cli@latest hook install claude-code
npx -y @dotcontext/cli@latest hook install codex --local
npx -y @dotcontext/cli@latest hook install pi --local

# MCP for Pi (optional, alongside the extension)
npx -y @dotcontext/mcp install pi

Install docs: Using with Hooks · Using with Pi

The runtime now follows one rule:

cli ──► harness ◄── mcp
         ▲
         └── integrations (Claude Code · Codex CLI · Pi)

Harness owns workflow, execution state, context scaffolding, sensors, and domain rules.
Adapters own transport, installation, and host-specific rendering — they call into the harness; they do not duplicate PREVC logic.

Why

On main, runtime code lived under src/services with workflow, harness, MCP gateway, and semantic tooling mixed together. That made it hard to:

• reuse the runtime outside MCP/CLI
• test domain rules without pulling in transport code
• add new host surfaces (hooks, Pi) without copying workflow behavior

This refactor consolidates reusable logic under src/harness, moves operator and protocol code to src/cli / src/mcp / src/integrations, and enforces the split with architecture boundary tests.

Removed — BREAKING CHANGES

• Legacy .context layout auto-migration removed. Pre-1.0 checkouts using
  .context/harness/ or .context/workflow/ are no longer migrated on access.
  The runtime reads only the canonical .context/config/ (authored config) and
  .context/runtime/ (generated state) layout. Migrate old folders manually before
  upgrading. (Removed src/shared/fs/legacyLayoutMigration.ts and all call sites.)
• Legacy workflow status.yaml migrator removed. .context/workflow/status.yaml
  is no longer read or migrated into canonical runtime/workflows/prevc.json.
  (Removed src/harness/domain/workflow/legacy/.)
• Legacy harness-session binding fallback removed. The old
  .context/workflow/harness-session.json binding is no longer read, rewritten,
  or archived. Bindings live only in runtime/workflows/prevc.json.
• Legacy tool-surface import/export targets removed. Imports and exports now
  cover only current-format surfaces. Dropped: .cursorrules and .cursor/rules/*.md;
  older .claude/*.memory and .claude/settings.json; .github/copilot/* and
  .github/.copilot/*; .windsurfrules; .clinerules; .continuerules and
  .continue/config.json; .codex/instructions.md; the Antigravity .agent/*
  layout (use .agents/*).
• Legacy Cursor .cursorrules export preset removed. Exporting to Cursor writes
  .cursor/rules (.mdc) only — the flat .cursorrules file is no longer emitted.
• Deprecated re-export shims removed: src/mcp/mcpServer.ts,
  src/mcp/mcpInstallService.ts, src/mcp/actionLogger.ts, src/mcp/gatewayTools.ts,
  src/cli/services/stateDetector.ts, src/cli/services/state/, and
  …/scaffolding/generators/shared/scaffoldStructures.ts. Import from the canonical
  modules instead (src/mcp/server, src/mcp/logging, src/mcp/gateway,
  src/harness/application/context/stateDetector, …/generators/shared/structures).
• Legacy enterprise project scale removed. Use large;
  getScaleFromName('enterprise') no longer maps to LARGE.
• Deprecated role helpers removed: SPECIALIST_TO_ROLE, getRoleForSpecialist,
  and getSpecialistsForRole (src/harness/domain/workflow/roles.ts). Use the
  agent-based orchestration model (ROLE_TO_AGENTS).
• PrevcStatusManager constructor signature changed from
  new PrevcStatusManager(contextPath, workflowState) to
  new PrevcStatusManager(workflowState) — the legacy contextPath argument
  (only used to locate the old status.yaml) is gone.
• Stopped gitignoring legacy runtime paths. .context/harness/** and
  .context/workflow/** are no longer added to the generated .gitignore.

Changed

• MCP install: Gemini — merged gemini-cli into a single gemini registry id; gemini-cli remains a one-release alias for install commands.
• MCP detection paths — Windsurf and Amazon Q detection now checks alternate config directories.
• Documentation — updated architecture, installation, and contributor docs for integrations, hooks, and Pi; MCP client count is now 17.
• Reorganized the on-disk .context data layout into authored config vs generated runtime state. The single .context/harness/ folder (which mixed editable config with machine-generated state) and the separate .context/workflow/ folder are replaced by:
  • .context/config/ — authored, version-controlled config: policy.json, sensors.json (moved from .context/harness/)
  • .context/runtime/ — all generated state, gitignored as one block:
    • runtime/sessions/<id>/ — one folder per session co-locating session.json, trace.jsonl, and artifacts/ (previously flat under harness/sessions, harness/traces, harness/artifacts)
    • runtime/workflows/ — PREVC state (prevc.json), plan tracking (plans.json, plan-tracking/), and collaboration-sessions.json (previously split across harness/workflows and workflow/)
    • runtime/contracts/ — task and handoff contracts (was harness/contracts)
    • runtime/evaluations/{replays,datasets}/ — replay and failure-dataset output (was harness/replays, harness/datasets)
  • All paths now resolve through a single source of truth (resolveRuntimeLayout in src/shared/fs/pathHelpers.ts) instead of hand-built 'harness'/'workflow' path segments.
  • The src/harness code module is unchanged — only the on-disk data folder moved. This release does not migrate pre-1.0 layouts (see Removed, above); move .context/harness/ and .context/workflow/ to .context/config/ and .context/runtime/ manually if upgrading an old checkout.
  • A layering test forbids src/harness/domain code from importing the application/adapters layers, and a boundary test forbids src/harness from importing the cli/mcp surfaces, keeping the runtime decoupled and reusable.

Added

• Hook install CLI — dotcontext hook install, hook dispatch, and hook uninstall for Claude Code, Codex CLI, and Pi, with --local, --global, --dry-run, and Codex-specific --format json|toml.
• Host hook runtime — typed event mappers and response adapters for Claude Code, Codex CLI, and Pi (session_start, PostToolUse, Stop / agent_end), wired through a shared harness hook adapter.
• Adapter-neutral workflow guidance — workflow-guide now exposes PREVC next steps, relevant skills, and portable gate decision hints through the harness, MCP, hooks/Pi renderers, and dotcontext admin workflow guide.
• @dotcontext/integrations package — publishable host hook adapters and mappers (./claude-code, ./codex, ./pi-dev subpaths).
• @dotcontext/pi package — Pi npm extension for in-process lifecycle hooks (bootstrap, tracing, workflow reminders).
• MCP install: Pi — npx @dotcontext/mcp install pi writes .mcp.json (local) or ~/.config/mcp/mcp.json (global).
• Built-in skill catalog — single source of truth for built-in skill slugs, PREVC phase mapping, and generated dotcontext-workflow-{p,r,e,v,c} meta skills.
• Built-in tests-passing sensor (src/services/harness/sensors/testsPassing.ts)
  • Default kind: 'jest' runs npm test -- --runInBand --json, parses jest's JSON output, and reports { numPassedTests, numFailedTests, numTotalTestSuites, failures: [{ name, message }] }; passes iff exit 0 and numFailedTests === 0
  • kind: 'exit-code' mode for non-jest runners passes iff the configured testCommand argv exits 0
  • Configurable testCommand (string[]) and timeoutMs (default 300s); spawn(..., { shell: false }) with explicit argv — no shell interpolation
  • Registered by default in HarnessSessionFacade.registerDefaultSensors
• Built-in typecheck-clean sensor (src/services/harness/sensors/typecheckClean.ts)
  • Default command npx tsc --noEmit; passes iff exit 0
  • On failure, captures the last tailLines (default 50) of combined stdout/stderr on output.tail plus the output.exitCode
  • Configurable command (string[]), timeoutMs (default 120s), and tailLines
  • Registered by default in HarnessSessionFacade.registerDefaultSensors
• **...

v0.9.2

Fixed

• Local release bundles are now executable through npx from the bundle root
  • build:packages now generates package-local node_modules/.bin shims for bin-bearing bundles
  • smoke:packages now verifies npm exec against the generated cli and mcp bundle roots instead of checking only static manifest fields

v0.9.1

Fixed

• @dotcontext/mcp install now honors the guided install flow
  • Running npx @dotcontext/mcp install in an interactive terminal now opens the same tool-selection prompt used by the main CLI compatibility command
  • Non-interactive runs without an explicit tool continue to fall back to all detected tools
  • The standalone MCP package now prints the post-install restart hint after successful installs, matching the CLI flow

v0.9.0

Why this release matters

0.9.0 is the release where dotcontext stops being described primarily as a CLI plus MCP installer and becomes a harness engineering runtime for agent-driven software delivery.

The reason for this shift is practical:

• The project already had three distinct responsibilities in the same codebase: operator commands, MCP transport, and runtime orchestration/state.
• Keeping those concerns blurred made the product harder to evolve, harder to reason about, and harder to make reliable for long-running agent workflows.
• The new harness layer makes the execution model explicit: sessions, traces, artifacts, sensors, task contracts, handoffs, policy, replay, and workflow state are now first-class runtime concerns instead of incidental side effects spread across the CLI and MCP adapters.

In product terms, this release establishes the architecture the project was already converging toward:

• dotcontext CLI for operator-facing sync, reverse-sync, install, and local admin flows
• dotcontext/harness as the reusable runtime and control plane
• dotcontext/mcp as the transport adapter agents talk to

This release does not just add new commands. It changes what the product is for:

• from scaffolding and sync around .context
• to a runtime that can govern how agents operate, validate work, exchange artifacts, persist execution state, and expose that behavior consistently through MCP and workflow layers

That is why many of the changes below are structural. The value of 0.9.0 is not only new functionality, but that the system now has a coherent runtime model instead of multiple partially overlapping ones.

Added

• Harness runtime foundation: added a transport-agnostic harness layer with durable sessions, traces, artifacts, and checkpoints under .context/harness

  • New runtime state service for persistent execution state shared by CLI, workflow, and MCP adapters
  • Session quality snapshots with backpressure evaluation and task completion checks

• Current tool-surface support in sync/export flows

  • Added primary-surface support for GEMINI.md exports/imports for Gemini CLI
  • Added GitHub Copilot skill export/import support via .github/skills
  • Added Windsurf skill export/import support via .windsurf/skills
  • Added support for GitHub Copilot agent filename compatibility using .agent.md
  • Added support for per-tool agent filename suffixes and per-tool rules file extensions in the unified tool registry

• Bootstrap policy scaffolding: context init now also materializes a project-local harness policy document

  • Repositories now start with explicit .context/harness/policy.json instead of relying on implicit runtime defaults
  • Bootstrap readiness now distinguishes configuration readiness from runtime readiness

• Harness quality controls: added first-class sensors, backpressure policies, task contracts, and handoff contracts

  • Sensors can persist execution evidence and block completion when critical checks fail
  • Task contracts now define required sensors, artifacts, outputs, and acceptance criteria
  • Handoff contracts provide explicit evidence and artifact tracking between agent roles

• Replay and dataset MVP: added replayable harness sessions and failure dataset generation

  • Durable session replay with ordered event logs across traces, artifacts, checkpoints, sensors, tasks, and handoffs
  • Failure dataset builder with repeated-signature clustering for sensor, task, session, and trace failures

• Harness policy engine: added persistent policy documents and rule-based runtime authorization

  • Policy rules can target tool, action, path, and risk
  • Support for allow, deny, and require_approval effects
  • MCP harness gateway now supports getPolicy, setPolicy, resetPolicy, registerPolicy, listPolicies, and evaluatePolicy

• Package productization workflow: added local packaging, smoke validation, and release preparation for split package distribution

  • build:packages prepares bundle outputs for cli, harness, and mcp
  • smoke:packages validates generated bundle manifests and exports
  • release:packages:patch|minor|major prepares local release directories in .release/releases/<version>

Changed

• Repositioned generated Q&A as an optional helper layer instead of a default context path

  • context init no longer enables generateQA by default
  • MCP and README descriptions now emphasize semantic context and snapshots as the primary codebase-understanding surface
  • searchQA is documented as keyword ranking over generated Q&A helper docs, not embedding-based semantic search

• Architectural split is now explicit: the codebase now follows cli -> harness <- mcp

  • src/cli is the operator-facing boundary
  • src/harness is the reusable runtime/domain boundary
  • src/mcp is the transport adapter boundary

• Updated CLI-facing documentation to reflect current public and hidden command surfaces, including admin workflow, admin skill, sync, reverse-sync, and the newer AI-tool context file conventions.

• Sync/export surfaces updated toward current conventions

  • Cursor rules directory exports now use .mdc files
  • Codex rules now export to AGENTS.md, while still importing legacy .codex/instructions.md
  • Google Antigravity now exports to .agents/rules and .agents/workflows while continuing to import legacy .agent/* layouts
  • Quick sync defaults and prompts now reflect the newer rules/skills target set for GitHub Copilot, Gemini, Windsurf, Codex, and Antigravity

• Skill scaffolding now produces stronger source content and cleaner exported skills

  • Scaffolded .context/skills/*/SKILL.md files now start with actionable starter sections (Workflow, Examples, Quality Bar, Resource Strategy) instead of near-empty placeholders
  • Built-in skill templates now bias toward concise procedural guidance, progressive disclosure, and trigger language in frontmatter descriptions instead of When to Use sections in the body
  • Exported AI-tool skills now use portable frontmatter with only name and description, improving compatibility with external skill runtimes

• PREVC workflow state is now harness-native

  • Canonical workflow state and workflow-to-session binding now live together under .context/harness/workflows/prevc.json
  • Legacy workflow-side binding files are treated only as migration inputs and are no longer part of the active runtime model

• Workflow integration now uses harness runtime controls

  • PREVC workflow initialization creates and binds harness sessions
  • Workflow advance can be blocked by harness completion checks
  • Workflow management records artifacts, checkpoints, tasks, handoffs, and sensor runs through the harness runtime

• Failure dataset generation is now canonical and side-effect free

  • Failure datasets are generated exclusively through datasetService
  • Replay generation for datasets no longer persists replay artifacts as a side effect

• Package root is now library-safe

  • The package root export now points at the CLI boundary instead of the process-bootstrapping entrypoint
  • MCP shutdown handling was centralized to avoid duplicate signal handlers and race conditions during server stop

• MCP package surface is now explicit

  • Preferred MCP installation now uses npx @dotcontext/mcp install
  • Generated AI-tool configs now start the server from @dotcontext/mcp instead of routing through the CLI package
  • The dedicated MCP package now supports both install and default server startup flows

• MCP gateway surface expanded

  • Added explicit harness operations for replay, dataset building, and policy document management
  • Harness-related gateway handlers are thinner and delegate to transport-agnostic services

• Removed dormant standalone AI SDK internals

  • Removed the unused src/services/ai runtime, provider auto-detection, and the old standalone provider dependency path
  • Moved the active scaffolding and explore helpers into src/services/harness/contextTools.ts to keep reusable execution logic inside the harness boundary
  • Kept semantic analysis centered on the active tree-sitter and optional LSP pipeline instead of bundling unused provider SDK dependencies

Fixed

• Policy enforcement consistency

  • Aligned workflow and MCP policy handling around a single harness policy model
  • Fixed policy document operations through the MCP harness gateway
  • Sensor execution now goes through harness policy authorization
  • MCP evaluatePolicy now maps target/action/path/approval inputs correctly

• Sync/export metrics and auditability

  • SyncService.run() now returns aggregate results instead of only printing UI output
  • ContextExportService now reports the real number of exported agent files instead of a placeholder count
  • ReverseQuickSyncService now uses real import results for rules and agents instead of detection counts

• Reverse-sync signal quality

  • Skill detection now imports only canonical SKILL.md files instead of treating any markdown file under skill directories as a skill
  • Agent import normalizes .agent.md filenames back into canonical .context/agents/*.md
  • Rules imported from non-markdown sources now normalize to .md targets in .context/docs
  • Skill merge mode now avoids re-appending identical imported content

• Skill fill/export consistency

  • Skill refill detection now respects scaffold status: unfilled metadata instead of weak placeholder/size heuristics
  • Exporting built-in skills now falls back to the stronger canonical template body when a scaffolded source file still has no meaningful body content

• **Packaging val...

v0.8.1

What's Changed

• Replace JSON import with fs.readFileSync for package metadata by @vinilana in #54

v0.8.0

[0.8.0] - 2026-03-21

Changed

• BREAKING: Renamed package from @ai-coders/context to @dotcontext/cli

  • CLI command changed from ai-context to dotcontext
  • MCP server name changed from ai-context to dotcontext
  • Why: The previous name caused frequent confusion with Context7 during
    prompt-based installation and search. "context" is too generic in the
    AI/LLM space. The new name "dotcontext" is unique, searchable, and
    directly references the .context/ directory convention that is the
    core of this tool.
  • Migration: Replace ai-context with dotcontext in your shell aliases
    and MCP configurations. Re-run npx @dotcontext/cli mcp:install to
    update all tool integrations.

• BREAKING: Standalone CLI no longer generates context or plans

  • Context creation, filling, and refresh are now MCP-only — your AI tool provides the LLM
  • Plan initialization and management moved to MCP tools (context and plan gateways)
  • The standalone CLI is now focused on workflow management, sync, reverse sync, imports, and MCP setup
  • Migration: Run npx @dotcontext/cli mcp:install and use your MCP-connected AI tool for context and plan operations

Added

• Themed Inquirer Prompts: Applied custom theme to all interactive prompts via new themedPrompt.ts wrappers (themedSelect, themedConfirm, themedInput, themedPassword, themedCheckbox), replacing raw inquirer calls with consistently styled interactions using the project's two-tone color scheme.

• "View Pending Files" Option: When the CLI detects unfilled scaffold files, users can now see which specific files need content before deciding to fill them.

• Smart Defaults Transparency: The interactive flow now displays detected project information on startup (e.g., "Detected: TypeScript project, openrouter provider configured") instead of silently using auto-detected values.

• API Key Format Validation: Lightweight format checks warn users when an API key doesn't match the expected prefix for a provider (e.g., sk- for OpenAI, sk-ant- for Anthropic). Non-blocking warnings only.

• "Back" Navigation in Prompt Flows: Added escape options in promptAnalysisOptions() and promptLLMConfig() so users can return to the previous menu instead of being forced through multi-step flows.

• Comprehensive .context Content: Rewrote all scaffolding files with project-specific content:

  • 4 documentation guides (project-overview, development-workflow, testing-strategy, tooling)
  • 7 agent playbooks with codebase-specific workflows and file references
  • 10 skill files (repurposed api-design to MCP Tool Design)
  • 3 QA guides (getting-started, project-structure, error-handling)
  • 1 development plan (simplify-interactive-cli)

• Skills System: Full skill scaffolding exported to .claude/skills/, .gemini/skills/, .codex/skills/

• Multi-tool Context Export: Context now syncs to Claude Code, Cursor, GitHub Copilot, Codex, Windsurf, and Gemini

• Codex MCP Install Support: mcp:install now supports Codex CLI directly

  • Writes MCP configuration to .codex/config.toml
  • Uses the documented [mcp_servers.dotcontext] TOML configuration block
  • Brings Codex in line with other first-class MCP install targets

• GitIgnore Integration in FileMapper: Automatic .gitignore respect prevents stack overflow in large repositories

  • New GitIgnoreManager class with spec-compliant .gitignore parsing via ignore npm package
  • O(1) cached lookups with hierarchical .gitignore loading from repo root
  • Graceful fallback to existing hardcoded excludes when no .gitignore found
  • Integrated into FileMapper.getRepoStructure() before glob scanning

• Path Traversal Protection for MCP Server: Security hardening for all file operations

  • New PathValidator class with null byte, URL-encoding, and traversal detection
  • SecurityError class with forensics metadata (attempted path, attack type)
  • Validates filePath, rootPath, and cwd params in wrapWithActionLogging() before tool execution

• Semantic Context Cache: In-memory caching for SemanticContextBuilder output

  • TTL-based expiration (default 5 minutes) with directory mtime invalidation
  • Per-repo and global invalidation methods
  • Integrated into MCP registerResources() context handler

• CLI Modular Architecture: Extracted command groups from monolithic index.ts

  • New CLIDependencies interface for dependency injection
  • Skill commands (5 subcommands) extracted to src/cli/commands/skillCommands.ts
  • Workflow commands (6 subcommands) extracted to src/cli/commands/workflowCommands.ts
  • index.ts reduced from 2818 to 2478 lines

Fixed

• needsFill() false positives: Fixed bug where needsFill() matched status: unfilled in document body content (e.g., code examples in agent playbooks) instead of only checking the YAML frontmatter block. The function now parses only the frontmatter between --- delimiters.

• configSummary i18n: displayConfigSummary() now uses the _t() translation function instead of hardcoded English labels ("Config:", "Options:", "Yes", "No").

• Missing i18n key: Added agent.type.skill translation key (en + pt-BR) that was referenced but undefined.

• Guide Consistency: Updated the user guide to match the real CLI surface

  • Clarifies that quick sync still exists in the interactive CLI
  • Removes the mismatch where Codex was described as an MCP install target before it was actually supported

• Frontmatter-Safe Fill Pipeline: 100% preservation of YAML frontmatter during fill operations

  • needsFill() now reads 15 lines (was 3) to detect status: in v2 scaffold format
  • processTarget() and processTargetWithAgent() now preserve frontmatter with status: filled update
  • collectTargets() filters by needsFill() with --force override to prevent re-filling
  • Added force option to FillCommandFlags and ResolvedFillOptions

Security

• Path traversal attacks via ../, URL encoding (%2e%2e), and null bytes now blocked in MCP tool handlers
• Audit logging for security events with forensics metadata

Performance

• Context generation 80-95% faster for unchanged files via semantic caching
• Eliminated stack overflow crashes in repositories with large unignored directories

Technical Details

New Files

• src/utils/gitignoreManager.ts — GitIgnoreManager with hierarchical .gitignore loading
• src/utils/gitignoreManager.test.ts — 18 tests
• src/utils/pathSecurity.ts — PathValidator with comprehensive sanitization
• src/utils/pathSecurity.test.ts — 18 tests
• src/services/semantic/contextCache.ts — In-memory TTL cache with mtime invalidation
• src/services/semantic/contextCache.test.ts — 13 tests
• src/cli/types.ts — CLIDependencies interface
• src/cli/commands/index.ts — Barrel export
• src/cli/commands/skillCommands.ts — Extracted skill subcommands
• src/cli/commands/workflowCommands.ts — Extracted workflow subcommands
• src/tests/integrity/postRefactoringIntegrity.test.ts — 26 integration tests

Modified Files

• src/utils/fileMapper.ts — GitIgnoreManager integration
• src/utils/frontMatter.ts — needsFill() increased to 15 lines
• src/services/fill/fillService.ts — Frontmatter preservation, force option, needsFill filtering
• src/services/mcp/mcpServer.ts — PathValidator + ContextCache integration
• src/index.ts — Replaced inline skill/workflow commands with modular imports
• package.json — Added ignore dependency

Removed

• Irrelevant QA docs: Removed api-endpoints.md (no REST API), deployment.md (npm package, not deployed service), and testing.md (redundant with testing-strategy.md).

Acknowledgements

Special thanks to @LorranHippolyte and @jeansassi for their massive contributions through pull requests.

v0.7.1

[0.7.1]

Included Pull Requests

• #31 - fix: exclude venv from semantic analysis
  • Excludes venv/ and .venv/ from semantic analysis by default to avoid noisy Python environment paths.
  • Persists user-defined exclude patterns during init, so fillSingle uses project-specific exclusions.
  • Aligns semantic analysis to shared default exclude patterns for consistent behavior across tools.
• #23 - [Fix] Auto-fill files without LLMs
  • Adds project-type-aware filtering so generated scaffolding better matches CLI, web, backend, and other stacks.
  • Introduces static defaultContent across docs, agents, and skills, enabling usable output without LLM enhancement.
  • Replaces placeholder scaffold content with practical starter templates.

Added

• Project Type Filtering in InitService: Scaffolds are now automatically filtered based on detected project type

  • Uses StackDetector and classifyProject to determine project type (cli, web-frontend, web-backend, full-stack, mobile, library, monorepo, desktop)
  • Passes filteredDocs and filteredAgents to generators based on project classification
  • CLI projects get core scaffolds only; web projects get additional architecture, security, and specialist agents
  • Graceful fallback to all scaffolds if classification fails

• Static Default Content for Scaffolds: All scaffolds now include useful template content out-of-the-box

  • New defaultContent field in ScaffoldSection type provides static content when not autoFilled
  • Serialization uses defaultContent directly instead of placeholder text ("Content to be added.")
  • Works immediately without requiring LLM enhancement or semantic analysis

• Agent Playbook Default Content: All 14 agent playbooks now include comprehensive static content

  • Mission — Clear description of agent purpose and when to engage
  • Responsibilities — Concrete list of tasks the agent handles
  • Best Practices — Guidelines for effective agent operation
  • Collaboration Checklist — Step-by-step workflow with checkboxes
  • Agents: code-reviewer, bug-fixer, feature-developer, refactoring-specialist, test-writer, documentation-writer, performance-optimizer, security-auditor, backend-specialist, frontend-specialist, architect-specialist, devops-specialist, database-specialist, mobile-specialist

• Documentation Default Content: 8 core documentation templates now include useful starter content

  • project-overview.md — Quick facts, entry points, technology stack, getting started checklist
  • development-workflow.md — Branching model, local development commands, code review expectations
  • testing-strategy.md — Test types, running tests, quality gates, troubleshooting
  • architecture.md — System overview, layers, patterns table, diagrams placeholder
  • tooling.md — Required tools, automation commands, IDE setup recommendations
  • security.md — Authentication, secrets management, compliance checklist
  • glossary.md — Type definitions, enums, core terms, acronyms table
  • data-flow.md — Module dependencies, service layer, high-level flow diagram

• Skill Default Content: All 10 built-in skills now include comprehensive static content

  • When to Use — Clear activation triggers for each skill
  • Instructions — Step-by-step execution guide
  • Examples — Concrete, copy-pasteable examples
  • Guidelines — Best practices for effective use
  • Skills: commit-message, pr-review, code-review, test-generation, documentation, refactoring, bug-investigation, feature-breakdown, api-design, security-audit

Changed

• Scaffold Generation: Scaffolds now generate with useful content instead of empty placeholders
  • Previously: _Content to be added._ with guidance comments
  • Now: Practical template content that works for any project type
  • AutoFill still enhances with project-specific content when semantic analysis is available

Fixed

• Exclude Python virtual environments from semantic analysis by default
  • Added venv/ and .venv/ to default exclude patterns
  • Unified SemanticContextBuilder to use shared default exclude patterns
  • Persisted user-provided exclude patterns from init into .context/config.json so fillSingle respects them

Technical Details

Modified Files

• src/services/init/initService.ts — Added project type detection and scaffold filtering
• src/generators/shared/structures/types.ts — Added defaultContent field to ScaffoldSection
• src/generators/shared/structures/serialization.ts — Updated to use defaultContent when available
• src/generators/shared/structures/agents/factory.ts — Added AgentDefaultContent interface and section mapping
• src/generators/shared/structures/agents/definitions.ts — Added default content for all 14 agents
• src/generators/shared/structures/skills/factory.ts — Added SkillDefaultContent interface and section mapping
• src/generators/shared/structures/skills/definitions.ts — Added default content for all 10 skills
• src/generators/shared/structures/documentation/projectOverview.ts — Added default content
• src/generators/shared/structures/documentation/workflow.ts — Added default content
• src/generators/shared/structures/documentation/testing.ts — Added default content
• src/generators/shared/structures/documentation/architecture.ts — Added default content
• src/generators/shared/structures/documentation/tooling.ts — Added default content
• src/generators/shared/structures/documentation/security.ts — Added default content
• src/generators/shared/structures/documentation/glossary.ts — Added default content
• src/generators/shared/structures/documentation/dataFlow.ts — Added default content
• src/services/semantic/types.ts — Added venv/ and .venv/ to default exclude patterns
• src/services/semantic/contextBuilder.ts — Uses shared default exclude patterns in semantic analysis
• src/services/ai/tools/initializeContextTool.ts — Persists user exclude patterns in .context/config.json
• src/services/ai/tools/fillScaffoldingTool.ts — Applies persisted exclude patterns during fillSingle

v0.7.0

[0.7.0]

Added

• Interactive Mode Environment Prompt: Ask user before loading .env file in interactive mode

  • Prompts "Load environment variables from .env file?" at startup
  • Default is No for explicit/secure approach
  • Command-line mode still loads .env automatically (no change)
  • MCP mode continues to skip .env loading (existing behavior)

• MCP Install Command: New mcp:install CLI command for easy MCP server configuration

  • Automatically configures ai-context MCP server in AI tools (Claude Code, Cursor, Windsurf, Cline, Continue.dev)
  • Interactive mode with tool detection and selection
  • Supports global (home directory) and local (project directory) installation
  • Merges with existing MCP configurations without overwriting
  • Dry-run mode for previewing changes
  • Bilingual support (English and Portuguese)

• Gateway Tools Consolidation: Unified MCP tools into 9 focused tools (5 gateways + 4 dedicated workflow tools)

  • explore - File and code exploration (read, list, analyze, search, getStructure)
  • context - Context scaffolding and semantic context (check, init, fill, fillSingle, listToFill, getMap, buildSemantic, scaffoldPlan)
  • plan - Plan management and execution tracking (link, getLinked, getDetails, getForPhase, updatePhase, recordDecision, updateStep, getStatus, syncMarkdown, commitPhase)
  • agent - Agent orchestration and discovery (discover, getInfo, orchestrate, getSequence, getDocs, getPhaseDocs, listTypes)
  • skill - Skill management (list, getContent, getForPhase, scaffold, export, fill)
  • sync - Import/export synchronization (exportRules, exportDocs, exportAgents, exportContext, exportSkills, reverseSync, importDocs, importAgents, importSkills)
  • workflow-init - Initialize PREVC workflow (creates .context/workflow/)
  • workflow-status - Get current workflow status
  • workflow-advance - Advance to next phase
  • workflow-manage - Manage handoffs, collaboration, documents, gates
  • Standardized response utilities and shared context across all handlers
  • Improved organization, discoverability, and reduced cognitive load

• MCP Export Tools: New granular export tools for docs, agents, and skills

  • exportDocs - Export documentation from .context/docs/ with README indexing mode
  • exportAgents - Export agents from .context/agents/ (symlink by default)
  • exportContext - Unified export of docs, agents, and skills in one operation

• MCP Import Tools: Individual import tools for each content type

  • importDocs - Import documentation from AI tool directories into .context/docs/
  • importAgents - Import agents from AI tool directories into .context/agents/
  • importSkills - Import skills from AI tool directories into .context/skills/

• README Index Mode: New indexMode option for docs export

  • readme (default) - Export only README.md files as indices
  • all - Export all matching files (previous behavior)
  • Cleaner exports that reference documentation indices

• Content Type Registry: Extensible registry for future content types

  • ContentTypeRegistry in src/services/shared/contentTypeRegistry.ts
  • Supports docs, agents, skills, plans
  • Easy addition of new content types (prompts, workflows, etc.)

• Unified Context Export Service: Orchestrates export of all content types

  • ContextExportService combines docs, agents, and skills export
  • Configurable skip options for each content type
  • Consistent error handling and reporting

• MCP Response Optimization: New skipContentGeneration option for initializeContext

  • Reduces response size from ~10k tokens to ~500 tokens
  • Enables two-phase workflow: scaffold first, fill on-demand
  • Default true for MCP to reduce context usage
  • Use fillSingleFile or fillScaffolding tools to generate content when needed

• Workflow Gates System: Comprehensive gate checking for phase transitions

  • require_plan gate - Enforces plan creation before P → R transition
  • require_approval gate - Requires plan approval before R → E transition
  • Automatic gate settings based on project scale (QUICK, SMALL, MEDIUM, LARGE, ENTERPRISE)
  • Custom error types for gate violations (WorkflowGateError)
  • New getGates action to check current gate status
  • Unit tests for gate checking logic

• Workflow Autonomous Mode: Toggle autonomous execution for AI agents

  • setAutonomous action to enable/disable autonomous mode
  • Autonomous mode bypasses certain gates for faster iteration
  • Tracks reason for mode changes in workflow status

• Execution History Tracking: Detailed action logging throughout workflow lifecycle

  • ExecutionHistory structure tracks all workflow actions
  • Records phase starts, completions, plan linking, step execution
  • archive_previous option for workflow initialization (archive vs delete existing)
  • Methods to archive or clear plans and workflows

• Plan Execution Management: Step-level tracking and synchronization

  • updateStep action for updating individual step status
  • getStatus action for retrieving plan execution status
  • syncMarkdown action to sync tracking data back to plan markdown files
  • Detailed interfaces for step execution (StepExecution) and phase tracking (PhaseExecution)

• Git Integration for Plans: Commit completed phases directly from MCP

  • commitPhase action creates git commits for completed workflow phases
  • Optional co-authoring support with coAuthor parameter
  • Configurable staging patterns with stagePatterns (default: .context/**)
  • Dry-run mode for previewing commits
  • Commit tracking records hash and timestamp for each phase

• Breadcrumb Logging: Step-level execution trails for debugging

  • Enhanced PlanLinker with breadcrumb trail generation
  • generateResumeContext provides step-level context for session resumption
  • Actions tracked: step_started, step_completed, step_skipped
  • Improves AI agent ability to resume interrupted workflows

• V2 Scaffold System: New scaffold generation architecture

  • Frontmatter-only files that define structure without content
  • scaffoldStructure context passed to AI agents for content generation
  • Centralized scaffold structure definitions in scaffoldStructures.ts
  • Supports documentation, agents, and skills scaffolding
  • Improved validation and serialization of scaffold structures
  • Deprecated legacy templates in favor of new system

• Fill Tool Enhancements: Better context for content generation

  • fillSingleFile and fillScaffolding exports from scaffolding tools now include scaffold structure context
  • Semantic context integrated into fill instructions
  • Removed deprecated content generation functions
  • Enhanced error handling and user guidance

• Q&A Service: Question and answer generation from codebase (via MCP context gateway)

  • QAService for generating and searching Q&A entries
  • generateQA action in context gateway creates Q&A files from codebase analysis
  • searchQA action for semantic search over generated Q&A
  • Utilizes pre-computed codebase maps when available

• Topic & Pattern Detection: Automatic detection of functional patterns (via MCP context gateway)

  • TopicDetector identifies capabilities in codebase
  • Detects: authentication, database access, API endpoints, caching, messaging, etc.
  • detectPatterns and getFlow actions provide pattern analysis
  • Used to generate contextually relevant Q&A and architectural insights

• Context Metrics Service: Usage tracking for context tools (via MCP metrics gateway)

  • Tracks context tool usage and file reads
  • Provides insights into pre-computed context effectiveness
  • Guides optimization of codebase map generation
  • Accessible via metrics gateway with tracking and reporting actions

• Enhanced Tool Status: Improved response structures

  • New incomplete status for tracking pending actions
  • instruction field with clear next-step guidance
  • pendingWrites replaces requiredActions for clarity
  • checklist field for actionable task lists

• Scaffold Enhancement Prompt: Consistent MCP enhancement instructions across all scaffolding operations

  • New MCP_SCAFFOLD_ENHANCEMENT_PROMPT constant for standardized AI guidance
  • New createScaffoldResponse() helper ensures all scaffold responses include enhancement instructions
  • _actionRequired, _status: "incomplete", and _warning signals for AI agent awareness
  • enhancementPrompt field with clear workflow steps
  • nextSteps array with actionable instructions
  • pendingEnhancement list of files requiring content
  • Applied to: context init and scaffoldPlan MCP actions
  • Ensures AI agents always receive instructions to enhance scaffolding via MCP tools

Changed

• Context Initialization Simplified: .context folder creation now uses simple path logic instead of complex detection

  • .context is created in the specified path or current working directory
  • Cleaner, more predictable behavior without hidden traversal logic
  • Internal complexity reduced from 496 lines to ~20 lines
  • Public APIs remain unchanged - static factory methods (WorkflowService.create(), PlanLinker.create()) are preserved
  • Backwards compatibility maintained for existing code

• MCP Action Logging: Logs every MCP tool invocation to .context/workflow/actions.jsonl with sanitized metadata for auditability.

• Phase Orchestration Skills: Workflow responses now include recommended skills alongside agent orchestration for each PREVC phase.

• Workflow Status Serialization: Omits empty or default sections to keep status.yaml minimal and readable.

...