Full Code of vinilana/ai-coders-context for AI

main b578c4d731f2 cached
310 files
1.9 MB
473.0k tokens
1901 symbols
1 requests
Download .txt
Showing preview only (2,066K chars total). Download the full file or copy to clipboard to get everything.
Repository: vinilana/ai-coders-context
Branch: main
Commit: b578c4d731f2
Files: 310
Total size: 1.9 MB

Directory structure:
gitextract__l45jdix/

├── .context/
│   ├── agents/
│   │   ├── README.md
│   │   ├── bug-fixer.md
│   │   ├── code-reviewer.md
│   │   ├── documentation-writer.md
│   │   ├── feature-developer.md
│   │   ├── performance-optimizer.md
│   │   ├── refactoring-specialist.md
│   │   └── test-writer.md
│   ├── docs/
│   │   ├── README.md
│   │   ├── codebase-map.json
│   │   ├── development-workflow.md
│   │   ├── harness-roadmap.md
│   │   ├── harness-split-foundation.md
│   │   ├── project-overview.md
│   │   ├── qa/
│   │   │   ├── README.md
│   │   │   ├── error-handling.md
│   │   │   ├── getting-started.md
│   │   │   └── project-structure.md
│   │   ├── testing-strategy.md
│   │   └── tooling.md
│   └── skills/
│       ├── README.md
│       ├── api-design/
│       │   └── SKILL.md
│       ├── bug-investigation/
│       │   └── SKILL.md
│       ├── code-review/
│       │   └── SKILL.md
│       ├── commit-message/
│       │   └── SKILL.md
│       ├── documentation/
│       │   └── SKILL.md
│       ├── feature-breakdown/
│       │   └── SKILL.md
│       ├── pr-review/
│       │   └── SKILL.md
│       ├── refactoring/
│       │   └── SKILL.md
│       ├── security-audit/
│       │   └── SKILL.md
│       └── test-generation/
│           └── SKILL.md
├── .env.example
├── .github/
│   ├── PULL_REQUEST_BODY.md
│   └── workflows/
│       ├── ci.yml
│       └── release.yml
├── .gitignore
├── .npmignore
├── AGENTS.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── CLAUDE.md
├── CONTRIBUTING.md
├── CONVENTIONS.md
├── LICENSE
├── README.md
├── docs/
│   ├── CONTEXT-WORKFLOW-HARNESS-CLI-PTBR.md
│   └── GUIDE.md
├── example-documentation.ts
├── jest.config.js
├── package.json
├── prompts/
│   ├── update_plan_prompt.md
│   └── update_scaffold_prompt.md
├── scripts/
│   ├── build-package-bundles.js
│   ├── release-packages.js
│   ├── smoke-package-bundles.js
│   └── test-mcp.js
├── src/
│   ├── cli/
│   │   ├── index.test.ts
│   │   └── index.ts
│   ├── cli.test.ts
│   ├── generators/
│   │   ├── agents/
│   │   │   ├── agentConfig.ts
│   │   │   ├── agentGenerator.test.ts
│   │   │   ├── agentGenerator.ts
│   │   │   ├── agentTypes.ts
│   │   │   ├── index.ts
│   │   │   └── templates/
│   │   │       ├── index.ts
│   │   │       ├── indexTemplate.ts
│   │   │       └── types.ts
│   │   ├── documentation/
│   │   │   ├── codebaseMapGenerator.ts
│   │   │   ├── documentationGenerator.test.ts
│   │   │   ├── documentationGenerator.ts
│   │   │   ├── guideRegistry.ts
│   │   │   ├── index.ts
│   │   │   └── templates/
│   │   │       ├── common.ts
│   │   │       ├── index.ts
│   │   │       ├── indexTemplate.ts
│   │   │       └── types.ts
│   │   ├── plans/
│   │   │   ├── index.ts
│   │   │   ├── planGenerator.test.ts
│   │   │   ├── planGenerator.ts
│   │   │   └── templates/
│   │   │       ├── indexTemplate.ts
│   │   │       ├── planTemplate.ts
│   │   │       └── types.ts
│   │   ├── shared/
│   │   │   ├── contextGenerator.ts
│   │   │   ├── directoryTemplateHelpers.ts
│   │   │   ├── generatorUtils.ts
│   │   │   ├── index.ts
│   │   │   ├── scaffoldStructures.ts
│   │   │   └── structures/
│   │   │       ├── agents/
│   │   │       │   ├── definitions.ts
│   │   │       │   ├── factory.ts
│   │   │       │   └── index.ts
│   │   │       ├── documentation/
│   │   │       │   ├── apiReference.ts
│   │   │       │   ├── architecture.ts
│   │   │       │   ├── dataFlow.ts
│   │   │       │   ├── glossary.ts
│   │   │       │   ├── index.ts
│   │   │       │   ├── migration.ts
│   │   │       │   ├── onboarding.ts
│   │   │       │   ├── projectOverview.ts
│   │   │       │   ├── security.ts
│   │   │       │   ├── testing.ts
│   │   │       │   ├── tooling.ts
│   │   │       │   ├── troubleshooting.ts
│   │   │       │   └── workflow.ts
│   │   │       ├── index.ts
│   │   │       ├── plans/
│   │   │       │   ├── index.ts
│   │   │       │   └── planStructure.ts
│   │   │       ├── registry.ts
│   │   │       ├── serialization.ts
│   │   │       ├── skills/
│   │   │       │   ├── definitions.ts
│   │   │       │   ├── factory.ts
│   │   │       │   └── index.ts
│   │   │       ├── types.ts
│   │   │       └── validation.ts
│   │   └── skills/
│   │       ├── index.ts
│   │       ├── skillGenerator.test.ts
│   │       ├── skillGenerator.ts
│   │       └── templates/
│   │           ├── indexTemplate.ts
│   │           └── skillTemplate.ts
│   ├── harness/
│   │   ├── index.test.ts
│   │   └── index.ts
│   ├── index.ts
│   ├── mcp/
│   │   ├── bin.test.ts
│   │   ├── bin.ts
│   │   ├── index.test.ts
│   │   └── index.ts
│   ├── prompts/
│   │   └── defaults.ts
│   ├── services/
│   │   ├── autoFill/
│   │   │   ├── autoFillService.ts
│   │   │   └── index.ts
│   │   ├── cli/
│   │   │   ├── index.ts
│   │   │   ├── mcpInstallService.test.ts
│   │   │   ├── mcpInstallService.ts
│   │   │   └── stateDetector.ts
│   │   ├── export/
│   │   │   ├── contextExportService.ts
│   │   │   ├── exportRulesService.ts
│   │   │   ├── index.ts
│   │   │   ├── skillExportService.test.ts
│   │   │   └── skillExportService.ts
│   │   ├── harness/
│   │   │   ├── agentsService.ts
│   │   │   ├── contextService.ts
│   │   │   ├── contextTools.test.ts
│   │   │   ├── contextTools.ts
│   │   │   ├── datasetService.test.ts
│   │   │   ├── datasetService.ts
│   │   │   ├── executionService.test.ts
│   │   │   ├── executionService.ts
│   │   │   ├── index.ts
│   │   │   ├── plansService.ts
│   │   │   ├── policyService.test.ts
│   │   │   ├── policyService.ts
│   │   │   ├── replayService.test.ts
│   │   │   ├── replayService.ts
│   │   │   ├── runtimeStateService.test.ts
│   │   │   ├── runtimeStateService.ts
│   │   │   ├── sensorCatalogService.ts
│   │   │   ├── sensorsService.test.ts
│   │   │   ├── sensorsService.ts
│   │   │   ├── skillsService.ts
│   │   │   ├── taskContractsService.test.ts
│   │   │   ├── taskContractsService.ts
│   │   │   └── workflowStateService.ts
│   │   ├── import/
│   │   │   ├── agentsDetector.ts
│   │   │   ├── importAgentsService.ts
│   │   │   ├── importRulesService.ts
│   │   │   ├── index.ts
│   │   │   ├── presets.ts
│   │   │   ├── rulesDetector.ts
│   │   │   └── types.ts
│   │   ├── mcp/
│   │   │   ├── README.md
│   │   │   ├── actionLogger.test.ts
│   │   │   ├── actionLogger.ts
│   │   │   ├── gateway/
│   │   │   │   ├── agent.ts
│   │   │   │   ├── context.test.ts
│   │   │   │   ├── context.ts
│   │   │   │   ├── explore.ts
│   │   │   │   ├── harness.test.ts
│   │   │   │   ├── harness.ts
│   │   │   │   ├── index.ts
│   │   │   │   ├── metrics.test.ts
│   │   │   │   ├── metrics.ts
│   │   │   │   ├── plan.ts
│   │   │   │   ├── response.ts
│   │   │   │   ├── shared.ts
│   │   │   │   ├── skill.ts
│   │   │   │   ├── sync.ts
│   │   │   │   ├── types.ts
│   │   │   │   ├── workflowAdvance.ts
│   │   │   │   ├── workflowInit.ts
│   │   │   │   ├── workflowManage.test.ts
│   │   │   │   ├── workflowManage.ts
│   │   │   │   ├── workflowStatus.test.ts
│   │   │   │   └── workflowStatus.ts
│   │   │   ├── gatewayTools.ts
│   │   │   ├── index.ts
│   │   │   ├── mcpInstallService.ts
│   │   │   ├── mcpServer.test.ts
│   │   │   └── mcpServer.ts
│   │   ├── qa/
│   │   │   ├── index.ts
│   │   │   ├── patternInferer.ts
│   │   │   ├── qaService.ts
│   │   │   └── topicDetector.ts
│   │   ├── quickSync/
│   │   │   ├── index.ts
│   │   │   └── quickSyncService.ts
│   │   ├── report/
│   │   │   ├── index.ts
│   │   │   └── reportService.ts
│   │   ├── reverseSync/
│   │   │   ├── importSkillsService.ts
│   │   │   ├── index.ts
│   │   │   ├── presets.ts
│   │   │   ├── reverseQuickSyncService.ts
│   │   │   ├── skillsDetector.ts
│   │   │   ├── toolDetector.ts
│   │   │   └── types.ts
│   │   ├── semantic/
│   │   │   ├── codebaseAnalyzer.test.ts
│   │   │   ├── codebaseAnalyzer.ts
│   │   │   ├── contextBuilder.ts
│   │   │   ├── contextCache.test.ts
│   │   │   ├── contextCache.ts
│   │   │   ├── index.ts
│   │   │   ├── lsp/
│   │   │   │   ├── index.ts
│   │   │   │   └── lspLayer.ts
│   │   │   ├── semanticSnapshotService.test.ts
│   │   │   ├── semanticSnapshotService.ts
│   │   │   ├── treeSitter/
│   │   │   │   ├── index.ts
│   │   │   │   └── treeSitterLayer.ts
│   │   │   └── types.ts
│   │   ├── shared/
│   │   │   ├── __tests__/
│   │   │   │   └── contextRootResolver.test.ts
│   │   │   ├── contentTypeRegistry.ts
│   │   │   ├── contextLayout.ts
│   │   │   ├── contextRootResolver.ts
│   │   │   ├── executionContext.ts
│   │   │   ├── globPatterns.ts
│   │   │   ├── index.ts
│   │   │   ├── pathHelpers.ts
│   │   │   ├── toolRegistry.ts
│   │   │   ├── types.ts
│   │   │   └── uiHelpers.ts
│   │   ├── stack/
│   │   │   ├── index.ts
│   │   │   ├── projectTypeClassifier.ts
│   │   │   ├── scaffoldFilter.ts
│   │   │   └── stackDetector.ts
│   │   ├── state/
│   │   │   ├── index.ts
│   │   │   ├── stateDetector.test.ts
│   │   │   └── stateDetector.ts
│   │   ├── sync/
│   │   │   ├── index.ts
│   │   │   ├── markdownReferenceHandler.ts
│   │   │   ├── presets.ts
│   │   │   ├── symlinkHandler.ts
│   │   │   ├── syncService.ts
│   │   │   └── types.ts
│   │   └── workflow/
│   │       ├── autoAdvance.ts
│   │       ├── index.ts
│   │       ├── workflowService.test.ts
│   │       └── workflowService.ts
│   ├── tests/
│   │   └── integrity/
│   │       └── postRefactoringIntegrity.test.ts
│   ├── types/
│   │   └── scaffoldFrontmatter.ts
│   ├── types.ts
│   ├── utils/
│   │   ├── cliUI.ts
│   │   ├── fileMapper.ts
│   │   ├── frontMatter.test.ts
│   │   ├── frontMatter.ts
│   │   ├── gitService.ts
│   │   ├── gitignoreManager.test.ts
│   │   ├── gitignoreManager.ts
│   │   ├── i18n.test.ts
│   │   ├── i18n.ts
│   │   ├── pathSecurity.test.ts
│   │   ├── pathSecurity.ts
│   │   ├── processShutdown.ts
│   │   ├── prompts/
│   │   │   ├── configSummary.ts
│   │   │   ├── index.ts
│   │   │   ├── smartDefaults.ts
│   │   │   └── types.ts
│   │   ├── splashScreen.test.ts
│   │   ├── splashScreen.ts
│   │   ├── theme.ts
│   │   ├── themedPrompt.ts
│   │   ├── versionChecker.test.ts
│   │   └── versionChecker.ts
│   ├── version.ts
│   └── workflow/
│       ├── agents/
│       │   ├── agentRegistry.ts
│       │   └── index.ts
│       ├── collaboration.ts
│       ├── errors.ts
│       ├── gates/
│       │   ├── gateChecker.test.ts
│       │   ├── gateChecker.ts
│       │   └── index.ts
│       ├── index.ts
│       ├── orchestration/
│       │   ├── agentOrchestrator.ts
│       │   ├── documentLinker.ts
│       │   └── index.ts
│       ├── orchestrator.ts
│       ├── phases.ts
│       ├── plans/
│       │   ├── index.ts
│       │   ├── planLinker.ts
│       │   └── types.ts
│       ├── prevcConfig.ts
│       ├── roles.ts
│       ├── scaling.ts
│       ├── skills/
│       │   ├── frontmatter.ts
│       │   ├── index.ts
│       │   ├── skillRegistry.ts
│       │   ├── skillTemplates.ts
│       │   └── types.ts
│       ├── status/
│       │   ├── statusManager.test.ts
│       │   ├── statusManager.ts
│       │   └── templates.ts
│       └── types.ts
├── templates/
│   └── packages/
│       ├── cli.README.md
│       ├── harness.README.md
│       └── mcp.README.md
└── tsconfig.json

================================================
FILE CONTENTS
================================================

================================================
FILE: .context/agents/README.md
================================================
# Agent Handbook

This directory contains ready-to-customize playbooks for AI agents collaborating on the current dotcontext codebase, including the transformation work toward `dotcontext/cli` and `dotcontext/harness`.

## Available Agents

- [Code Reviewer](./code-reviewer.md) -- Review code changes for quality, style, and best practices
- [Bug Fixer](./bug-fixer.md) -- Analyze bug reports and error messages
- [Feature Developer](./feature-developer.md) -- Implement new features according to specifications
- [Refactoring Specialist](./refactoring-specialist.md) -- Identify code smells and improvement opportunities
- [Test Writer](./test-writer.md) -- Write comprehensive unit and integration tests
- [Documentation Writer](./documentation-writer.md) -- Create clear, comprehensive documentation
- [Performance Optimizer](./performance-optimizer.md) -- Identify performance bottlenecks

## Harness Transformation Squad

- [Agent Systems Designer](./agent-systems-designer.md) -- Define the target agent topology, harness primitives, and product boundaries
- [CLI Experience Architect](./cli-experience-architect.md) -- Shape the `dotcontext/cli` experience and keep the CLI thin
- [Harness Platform Architect](./harness-platform-architect.md) -- Define the runtime and API surface for `dotcontext/harness`
- [Workflow Orchestration Engineer](./workflow-orchestration-engineer.md) -- Reframe PREVC, plans, agents, and skills as the harness control plane
- [Harness Quality Auditor](./harness-quality-auditor.md) -- Map guides, sensors, evaluations, and operational quality gates
- [Migration Release Manager](./migration-release-manager.md) -- Plan packaging, compatibility, rollout, and migration sequencing

## How To Use These Playbooks

1. Pick the agent that matches your task (e.g., `test-writer` when adding test coverage for a new service).
2. Open the playbook file and adapt the template with project-specific context:
   - Reference the relevant service under `src/services/` or generator under `src/generators/`.
   - Link to the corresponding doc in `.context/docs/` or plan in `.context/plans/`.
   - Include any active workflow phase or plan constraints.
3. Paste the final prompt into your AI assistant session.
4. After the task, capture learnings in the relevant documentation file (`.context/docs/`) so future runs improve.

## Related Resources

- [Documentation Index](../docs/README.md)
- [Harness Transformation Plan](../plans/dotcontext-harness-engineering-transformation.md)
- [Agent Knowledge Base](../../AGENTS.md)
- [Contributor Guidelines](../../CONTRIBUTING.md)


================================================
FILE: .context/agents/bug-fixer.md
================================================
---
type: agent
name: bug-fixer
description: Analyze bug reports and error messages
role: developer
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Bug Fixer

## Role

Diagnose and fix bugs in the dotcontext CLI tool. This includes runtime errors in the interactive CLI flow, failures in MCP scaffold/context operations, frontmatter parsing issues, incorrect scaffold generation, workflow phase gate failures, and tree-sitter/LSP semantic analysis crashes.

## Key Files to Understand

- `src/index.ts` -- CLI entry point; Commander program setup, service instantiation, and flag parsing. Most user-facing errors surface here.
- `src/types.ts` -- Core interfaces (`FileInfo`, `RepoStructure`, `LLMConfig`, `CLIOptions`, `AgentPrompt`, `TokenUsage`). Type mismatches often start here.
- `src/utils/frontMatter.ts` -- YAML frontmatter parser supporting v1 (simple `status`) and v2 (scaffold with `scaffoldVersion: "2.0.0"`). A frequent source of parsing edge cases.
- `src/services/mcp/gateway/context.ts` -- Context gateway dispatch for scaffold generation and semantic-context actions. Bugs here cascade into multiple MCP flows.
- `src/services/semantic/codebaseAnalyzer.ts` -- Tree-sitter + optional LSP analysis. Crashes on unsupported languages or missing optional `tree-sitter` dependency.
- `src/services/ai/tools/fillScaffoldingTool.ts` -- Scaffold fill helpers and semantic-context caching. Missing files, stale cache, and oversized payload issues surface here.
- `src/utils/cliUI.ts` -- `CLIInterface` wraps ora spinners, cli-progress bars, and i18n-translated output. Spinner lifecycle bugs (not stopping on error) are common.
- `src/workflow/gates/gateChecker.ts` -- PREVC phase gate validation. Gate check failures can block `workflow advance`.
- `src/services/shared/contextRootResolver.ts` -- Resolves the `.context/` root directory. Path resolution bugs affect init, fill, sync, and export.

## Workflow Steps

1. **Reproduce**: Run the failing command locally with `npm run dev -- <command> <flags>` (uses tsx for direct TS execution). Add `--verbose` for extended logging.
2. **Locate the error boundary**: Trace from `src/index.ts` command handler -> service `.run()` method -> downstream call. Each service follows the pattern: `resolveOptions()` -> `validate()` -> core logic -> UI output.
3. **Check frontmatter parsing**: If the bug involves `.context/` files, verify the frontmatter format. v2 scaffold files must have `scaffoldVersion: "2.0.0"` and a valid `type` field (`doc`, `agent`, `skill`, `plan`). Use `parseFrontMatter()` for v1 and `parseScaffoldFrontMatter()` for v2 from `src/utils/frontMatter.ts`.
4. **Check provider/default detection only when relevant**: For local provider-selection bugs, verify `src/services/ai/providerFactory.ts` and `src/utils/prompts/smartDefaults.ts`. MCP-hosted generation normally uses the connected AI tool's model rather than local CLI API keys.
5. **Run existing tests**: `npm test` executes Jest with ts-jest. Relevant test files:
   - `src/utils/frontMatter.test.ts`
   - `src/utils/contentSanitizer.test.ts`
   - `src/services/semantic/codebaseAnalyzer.test.ts`
   - `src/workflow/gates/gateChecker.test.ts`
   - `src/generators/agents/agentGenerator.test.ts`
   - `src/generators/plans/planGenerator.test.ts`
6. **Write a regression test**: Place it alongside the source file using the `*.test.ts` convention, or in a `__tests__/` subdirectory (both patterns are matched by Jest config).
7. **Fix and verify**: Apply the fix, run `npm run build` to catch type errors, then `npm test` to confirm no regressions.

## Best Practices

- Always check whether the bug occurs in v1 (legacy) or v2 (scaffold) frontmatter paths; they share function names but diverge in parsing logic.
- The `tree-sitter` and `tree-sitter-typescript` packages are optional dependencies. Wrap any tree-sitter usage in try/catch and degrade gracefully. See `CodebaseAnalyzer` constructor pattern.
- Services use dependency injection via constructor objects (e.g., `InitServiceDependencies`, `SyncServiceDependencies`). When mocking for tests, provide all required fields: `ui` (CLIInterface), `t` (TranslateFn), `version` (string).
- The i18n system (`src/utils/i18n.ts`) supports `en` and `pt-BR`. When fixing UI-facing strings, update both locale translation maps.
- Use `sanitizeAIResponse()` from `src/utils/contentSanitizer.ts` on any LLM output before writing to files -- it strips markdown fences and other artifacts.

## Common Pitfalls

- **Spinner not stopped on error**: `CLIInterface` uses ora spinners. If an error is thrown mid-operation without calling `spinner.fail()`, the terminal output breaks. Always stop spinners in catch blocks.
- **Path resolution assumptions**: `contextRootResolver.ts` walks up from cwd to find `.context/`. If tests or commands run from unexpected directories, paths resolve incorrectly. Always use `path.resolve()` with explicit base paths.
- **Scaffold file discovery**: `src/services/shared/globPatterns.ts` and the context tools must agree on which scaffold files are discoverable. New file types can be skipped if the discovery logic is not updated consistently.
- **PREVC phase ordering**: The phase order is strictly `['P', 'R', 'E', 'V', 'C']` (defined in `src/workflow/phases.ts`). Skipping phases requires the phase to be marked `optional: true`. Only `R` (Review) is optional by default.
- **Zod schema validation**: AI agent outputs are validated with Zod schemas (e.g., `DocumentationOutputSchema` in `src/services/ai/schemas.ts`). Schema mismatches from LLM responses cause silent failures if not caught.


================================================
FILE: .context/agents/code-reviewer.md
================================================
---
type: agent
name: code-reviewer
description: Review code changes for quality, style, and best practices
role: reviewer
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Code Reviewer

## Role

Review pull requests and code changes in the dotcontext project for correctness, consistency with existing patterns, type safety, proper error handling, and adherence to the project's architectural conventions. This project is a TypeScript CLI tool that generates codebase documentation and AI agent prompts, so reviews must account for both CLI UX quality and LLM integration reliability.

## Key Files to Understand

- `src/index.ts` -- CLI entry point using Commander. All commands are registered here. Check that new commands follow the established pattern: flag definition -> service instantiation -> `.run()` call.
- `src/types.ts` -- Shared type definitions. Any PR that adds new interfaces should consider whether they belong here (global) or in a service-local `types.ts` file.
- `tsconfig.json` -- Strict mode enabled, target ES2020, commonjs modules. The `baseUrl` is `./src` with a path alias `@generators/agents/*`.
- `jest.config.js` -- ts-jest preset, roots in `<rootDir>/src`, test match patterns: `**/__tests__/**/*.ts` and `**/?(*.)+(spec|test).ts`.
- `src/utils/theme.ts` -- Centralized color palette and symbols using chalk. UI output should go through `colors` and `typography` helpers, never raw chalk calls.
- `src/utils/i18n.ts` -- Translation system with `en` and `pt-BR` locales. Every user-facing string must use `t('key')` pattern.
- `src/services/shared/` -- Shared utilities: `pathHelpers.ts`, `llmConfig.ts`, `globPatterns.ts`, `contentTypeRegistry.ts`, `contextRootResolver.ts`, `uiHelpers.ts`, `toolRegistry.ts`. Common code should live here, not be duplicated across services.
- `src/generators/shared/` -- Shared generator utilities: `generatorUtils.ts`, `contextGenerator.ts`, `scaffoldStructures.ts`, and the structures registry under `structures/`.

## Workflow Steps

1. **Understand scope**: Read the PR description and diff. Identify which services, generators, or utilities are touched. Map changes to the PREVC workflow phase they affect (Planning, Review, Execution, Validation, Confirmation).
2. **Check type safety**: Run `npm run build` mentally or actually. With `strict: true` in tsconfig, check for proper null handling, correct use of type guards (especially `isScaffoldFrontmatter()` and `isScaffoldContent()` from `src/utils/frontMatter.ts`), and no `any` casts without justification.
3. **Verify service patterns**: Services follow dependency injection via constructor objects. Check that:
   - Dependencies are declared as interfaces (e.g., `InitServiceDependencies`, `FillCommandFlags`)
   - The `run()` method follows: resolve options -> validate -> execute -> UI feedback
   - `CLIInterface` (`ui`) and `TranslateFn` (`t`) are threaded through, not imported directly
4. **Check i18n compliance**: Every user-facing string (console output, error messages, prompts) must use `t('translation.key')` or `this.t('key')`. Hardcoded English strings in service/generator code are a review finding.
5. **Validate frontmatter handling**: If the PR touches `.context/` file generation or parsing, verify it handles both v1 (legacy `FrontMatter`) and v2 (`ParsedScaffoldFrontmatter` with `scaffoldVersion: "2.0.0"`) formats correctly.
6. **Review test coverage**: Check that new logic has corresponding tests. Tests should be co-located using `*.test.ts` or in `__tests__/` directories. Key test files to reference for patterns:
   - `src/utils/frontMatter.test.ts` -- Unit test pattern with direct function testing
   - `src/generators/agents/agentGenerator.test.ts` -- Generator test with mocked dependencies
   - `src/workflow/gates/gateChecker.test.ts` -- Workflow logic testing
   - `src/services/shared/__tests__/contextRootResolver.test.ts` -- Service test in `__tests__/` directory
7. **Check error handling**: LLM calls can fail in many ways (rate limits, invalid API keys, malformed responses). Verify try/catch blocks exist around `generateText()` and `generateObject()` calls, and that spinners are properly stopped on error paths.

## Best Practices

- **Barrel exports**: Each service and generator directory has an `index.ts` that re-exports public APIs. New exports should be added there, not imported via deep paths from outside the module.
- **Optional dependencies**: `tree-sitter` and `tree-sitter-typescript` are in `optionalDependencies`. Code using them must handle the case where they are not installed (dynamic import with try/catch).
- **Consistent flag naming**: CLI flags use camelCase in code (`useAgents`, `useLsp`, `autoFill`) and kebab-case on the command line (`--use-agents`, `--use-lsp`, `--auto-fill`). Commander handles the conversion.
- **Scaffold structure system**: The scaffold structure registry in `src/generators/shared/structures/` defines templates for docs, agents, skills, and plans. New content types must register in `registry.ts` and provide proper `ScaffoldStructure` definitions.
- **AI provider abstraction**: LLM interactions go through `LLMClientFactory` -> provider-specific clients. Never import `@ai-sdk/anthropic` or `@ai-sdk/google` directly in service code; use the factory pattern in `src/services/ai/providerFactory.ts`.

## Common Pitfalls

- **Missing `await` on fs-extra calls**: `fs-extra` methods like `ensureDir`, `writeFile`, `readFile` are async. Missing `await` causes race conditions that only manifest intermittently.
- **Glob pattern escaping**: The `glob` package (v10) uses different escaping rules than earlier versions. Patterns in `src/services/shared/globPatterns.ts` must use forward slashes even on Windows.
- **Translation key typos**: The i18n system silently returns the key string if a translation is missing. Review that new translation keys actually exist in the locale maps.
- **PREVC phase-role mismatches**: When modifying agent-to-phase mappings in `src/generators/agents/agentGenerator.ts` (`AGENT_PHASES`), verify the roles match those defined in `src/workflow/phases.ts` (`PREVC_PHASES`).
- **Inquirer v12 breaking changes**: The project uses `inquirer@^12.6.3` which has ESM/CJS compatibility nuances. Prompt definitions must match the v12 API.


================================================
FILE: .context/agents/documentation-writer.md
================================================
---
type: agent
name: documentation-writer
description: Create clear, comprehensive documentation
role: documenter
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Documentation Writer

## Role

Create and maintain documentation for the dotcontext project, both the user-facing README/guides and the internal `.context/` documentation that the tool itself generates. This includes writing doc templates, improving scaffold structures, updating the guide registry, and ensuring documentation accurately reflects the current CLI commands and service capabilities.

## Key Files to Understand

- `README.md` -- Project README, the primary user-facing documentation. Covers installation, CLI usage, commands, and configuration.
- `.context/docs/README.md` -- Index of generated documentation within the `.context/` directory structure.
- `.context/agents/README.md` -- Index of agent playbooks.
- `src/generators/documentation/documentationGenerator.ts` -- Core generator that scaffolds documentation files in `.context/docs/`. Creates files for project overview, architecture, API reference, testing, onboarding, etc.
- `src/generators/documentation/guideRegistry.ts` -- Registry of all documentation guide types (`DOCUMENT_GUIDES`). Each guide has a name, description, category, and template. Adding new documentation types starts here.
- `src/generators/documentation/templates/` -- Template functions that produce the initial content for each documentation type. Contains `common.ts` (shared template helpers), `indexTemplate.ts` (README index), and type definitions.
- `src/generators/shared/structures/documentation/` -- Scaffold structure definitions for each doc type: `projectOverview.ts`, `architecture.ts`, `apiReference.ts`, `testing.ts`, `onboarding.ts`, `workflow.ts`, `security.ts`, `tooling.ts`, `glossary.ts`, `troubleshooting.ts`, `migration.ts`, `dataFlow.ts`.
- `src/services/ai/tools/fillScaffoldingTool.ts` -- MCP scaffold-fill helpers. Understanding the context returned here is essential for writing templates that produce good output in connected AI tools.
- `src/services/autoFill/autoFillService.ts` -- Static auto-fill layer used during scaffold generation. Good structures improve both auto-filled starter content and MCP-guided completion.
- `src/utils/i18n.ts` -- Translation system. Documentation-related UI strings (section headers, progress messages) must be translatable.

## Workflow Steps

1. **Identify documentation gap**: Determine what needs documenting -- a new CLI command, a new service, a changed workflow, or an improvement to existing scaffold templates.
2. **Check the guide registry**: Review `src/generators/documentation/guideRegistry.ts` to see existing documentation types and their categories. Categories include: `overview`, `architecture`, `development`, `operations`.
3. **Update or create scaffold structures**: If adding a new documentation type, create a structure definition in `src/generators/shared/structures/documentation/` following the pattern of existing files (export a `ScaffoldStructure` with `fields`, `sections`, and `metadata`). Register it in the `index.ts` barrel.
4. **Write the template**: Add a template function in `src/generators/documentation/templates/` that generates the initial scaffold markdown. Use the `common.ts` helpers for consistent formatting. Templates should include YAML frontmatter with `type: doc`, `name`, `description`, `generated`, `status: unfilled`, and `scaffoldVersion: "2.0.0"`.
5. **Update the generator**: If adding new guide types, register them in `documentationGenerator.ts` so MCP `context({ action: "init" })` includes them.
6. **Test generation**: Run the relevant generator tests and verify the MCP context flow (`context init` + `fillSingle`) still provides the right scaffold structure and instructions.
7. **Verify i18n**: Add translation keys for any new user-facing strings to both `en` and `pt-BR` locales in `src/utils/i18n.ts`.

## Best Practices

- **Scaffold-first approach**: All documentation in `.context/` starts as a scaffold (status: `unfilled`) with structured sections and guidance. MCP clients then use the scaffold structure and semantic context to complete them. Write templates that give the AI clear section headings and context about what to include.
- **Frontmatter consistency**: Always use v2 scaffold frontmatter format with `scaffoldVersion: "2.0.0"`. Include `type`, `name`, `description`, `generated`, and `status` fields at minimum.
- **Use `serializeStructureForAI()` and `serializeStructureAsMarkdown()`**: These functions in `src/generators/shared/scaffoldStructures.ts` convert scaffold structures to formats consumable by the LLM or written to disk. Use them instead of hand-crafting markdown.
- **Content sanitization**: LLM-generated documentation passes through `sanitizeAIResponse()` from `src/utils/contentSanitizer.ts`. Be aware that it strips markdown code fences wrapping entire documents and normalizes whitespace.
- **Cross-reference with agents**: Documentation guides are referenced by agent playbooks via the `docs` field in frontmatter. When creating new documentation, consider which agents would benefit from referencing it.
- **Keep the codebase map updated**: `src/generators/documentation/codebaseMapGenerator.ts` generates an auto-updated codebase map. Any major structural changes should be reflected here.

## Common Pitfalls

- **Forgetting the index template**: When adding new documentation types, also update `src/generators/documentation/templates/indexTemplate.ts` so the `.context/docs/README.md` index includes a link to the new document.
- **Template vs. fill content confusion**: Templates generate the scaffold skeleton; MCP clients or auto-fill complete the actual content. Do not put project-specific details in templates -- those are inferred from the codebase during fill.
- **Stale documentation after refactoring**: After service or generator refactoring, re-run the MCP context flow to regenerate scaffolding and refresh filled content. The `dotcontext report` command can identify stale or unfilled documents.
- **Ignoring auto-fill**: The `AutoFillService` (`src/services/autoFill/`) can populate scaffolds with semantic data without an LLM. When writing structures, define auto-fill hints in the scaffold structure so auto-fill can provide baseline content.
- **Missing `getScaffoldStructure()` registration**: New scaffold types must be registered in `src/generators/shared/scaffoldStructures.ts` via `getScaffoldStructure()`. Without this, the fill pipeline cannot locate the structure definition for the document.


================================================
FILE: .context/agents/feature-developer.md
================================================
---
type: agent
name: feature-developer
description: Implement new features according to specifications
role: developer
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Feature Developer

## Role

Implement new features in the dotcontext CLI tool, including new CLI commands, services, generators, workflow capabilities, MCP tools, and integrations with LLM providers. Features must follow the project's established architecture: Commander-based CLI -> Service layer -> Generator/AI layer, with dependency injection, i18n support, and proper frontmatter handling.

## Key Files to Understand

- `src/index.ts` -- CLI entry point. All commands are registered here using Commander. New commands follow the pattern: `program.command('name').description().option().action(async () => { ... })`.
- `src/types.ts` -- Core shared types: `FileInfo`, `RepoStructure`, `LLMConfig`, `CLIOptions`, `AgentPrompt`, `TokenUsage`.
- `src/services/` -- Service layer. Each service lives in its own subdirectory with `index.ts` barrel export, a main service class, a `types.ts` for interfaces, and optionally a `presets.ts` for default configurations.
- `src/generators/` -- Content generators for `documentation`, `agents`, `plans`, and `skills`. Each generator creates scaffold files in `.context/`.
- `src/workflow/` -- PREVC workflow system: phases (`P`lanning, `R`eview, `E`xecution, `V`alidation, `C`onfirmation), roles, gates, orchestration, scaling, and status management.
- `src/services/ai/` -- AI integration layer: `providerFactory.ts` (provider helpers), `tools/` (code analysis and scaffold tools), `schemas/` (Zod schemas for structured output), and MCP-facing utilities.
- `src/services/mcp/` -- Model Context Protocol server implementation using `@modelcontextprotocol/sdk`.
- `src/utils/i18n.ts` -- i18n with `en` and `pt-BR` locales. The `TranslateFn` type and `createTranslator()` factory.
- `src/utils/cliUI.ts` -- `CLIInterface` class for all terminal output (spinners, progress bars, status messages, PREVC diagrams).
- `src/utils/theme.ts` -- Centralized chalk-based color scheme (`colors`, `symbols`, `typography`).
- `src/services/shared/` -- Cross-cutting utilities: path helpers, glob patterns, content type registry, context root resolution, and tool registry.

## Workflow Steps

1. **Plan the feature**: Identify which layers need changes. A typical feature touches: (a) CLI command definition in `src/index.ts`, (b) a new or existing service in `src/services/`, (c) possibly a generator in `src/generators/`, and (d) i18n keys in `src/utils/i18n.ts`.

2. **Create the service**: Follow the established directory pattern:
   - `src/services/<feature>/index.ts` -- Barrel export
   - `src/services/<feature>/<feature>Service.ts` -- Main service class
   - `src/services/<feature>/types.ts` -- Interfaces (command flags, dependencies, options)
   - `src/services/<feature>/presets.ts` -- Default configurations (optional)

   The service constructor takes a dependencies object with at minimum `ui: CLIInterface`, `t: TranslateFn`, and `version: string`. The main method is `async run(flags: CommandFlags): Promise<void>`.

3. **Register the CLI command**: In `src/index.ts`, import the service and add a new `program.command()` block. Follow existing patterns for flag definitions (use `.option()` with short and long forms). Instantiate the service with the shared `ui`, `t`, and `VERSION` dependencies.

4. **Add i18n translations**: Add all user-facing strings as translation keys in `src/utils/i18n.ts` for both `en` and `pt-BR` locales. Use the namespace pattern: `'<command>.<context>.<specific>'` (e.g., `'fill.progress.analyzing'`).

5. **Integrate with generators** (if producing `.context/` files): Use the scaffold structure system in `src/generators/shared/structures/`. Define a `ScaffoldStructure`, register it, and use `createAgentFrontmatter()` or equivalent from `src/types/scaffoldFrontmatter.ts` for proper v2 frontmatter.

6. **Add AI capabilities** (if MCP-facing): Extend `src/services/ai/tools/` and `src/services/mcp/gateway/` rather than adding standalone CLI agent classes. Reuse `providerFactory.ts` helpers only where the MCP server itself needs provider-aware behavior; content generation should flow through the connected MCP client.

7. **Write tests**: Create `<feature>Service.test.ts` or a `__tests__/` directory. Mock `CLIInterface` and `TranslateFn`. Use `jest.mock()` for fs-extra and external dependencies.

8. **Build and test**: Run `npm run build` (TypeScript compilation) then `npm test` (Jest). Test manually with `npm run dev -- <new-command> --verbose`.

## Best Practices

- **Dependency injection everywhere**: Never import `CLIInterface` or `TranslateFn` directly in services. Accept them via constructor dependency objects. This makes testing straightforward.
- **Use `resolveOptions()` pattern**: Services should have a private `resolveOptions()` method that merges CLI flags with defaults, resolves paths, and validates inputs before the main logic runs.
- **Respect the `.context/` directory structure**: All generated files go under `.context/` with subdirectories: `docs/`, `agents/`, `plans/`, `skills/`, `workflow/`. Use `contextRootResolver.ts` to find the correct root.
- **Provider-agnostic AI code**: Support all four providers (`openrouter`, `openai`, `anthropic`, `google`) via `providerFactory.ts`. Never hardcode a specific provider. The default model is defined as `DEFAULT_MODEL` in `src/index.ts`.
- **Graceful degradation for optional deps**: `tree-sitter` is optional. Any feature using semantic analysis must handle the case where it is not installed.

## Common Pitfalls

- **Not updating barrel exports**: After creating new files, update the `index.ts` in the parent directory to re-export them. Other parts of the codebase import from barrels, not deep paths.
- **Forgetting the version import**: `VERSION` and `PACKAGE_NAME` come from `src/version.ts`, not `package.json` directly. Use these constants for consistency.
- **Commander flag name mismatch**: Commander converts `--my-flag` to `myFlag` in the options object. Be careful with the camelCase conversion, especially for flags like `--use-lsp` -> `useLsp`.
- **Async service initialization**: Some services need async setup (e.g., reading config files). Do this in `run()`, not the constructor. Constructors must be synchronous.
- **Token limits with LLM agents**: When building agentic features, set reasonable `maxSteps` and `maxOutputTokens` limits. The `stepCountIs()` helper from the AI SDK can cap tool-use loops.


================================================
FILE: .context/agents/performance-optimizer.md
================================================
---
type: agent
name: performance-optimizer
description: Identify performance bottlenecks
role: developer
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Performance Optimizer

## Role

Identify and resolve performance bottlenecks in the dotcontext CLI tool. The primary performance concerns are: file system scanning speed (glob operations over large repositories), tree-sitter parsing throughput, semantic-context construction cost, MCP payload size, and CLI startup time. Since this is a developer tool that operates on entire codebases, performance at scale (repositories with thousands of files) is critical.

## Key Files to Understand

- `src/utils/fileMapper.ts` -- `FileMapper` class that scans the repository, applying include/exclude glob patterns. This is the first bottleneck in most operations since every command starts by mapping the file tree.
- `src/services/shared/globPatterns.ts` -- Default exclude patterns (node_modules, dist, coverage, .git, etc.). Poorly configured patterns cause FileMapper to scan too many files.
- `src/services/semantic/codebaseAnalyzer.ts` -- `CodebaseAnalyzer` orchestrates tree-sitter parsing. Has `maxFiles: 5000` default limit. The `treeSitter/treeSitterLayer.ts` handles per-file parsing.
- `src/services/semantic/contextBuilder.ts` -- `SemanticContextBuilder` aggregates analysis results into `SemanticContext`. Memory usage scales with number of extracted symbols.
- `src/services/ai/tools/fillScaffoldingTool.ts` -- Shared scaffold-fill tool. Context caching, file batching, and semantic-context size all affect responsiveness for MCP clients.
- `src/services/mcp/gateway/context.ts` -- Context gateway wiring. Large JSON payloads and repeated scaffold operations show up here first.
- `src/services/ai/tools/` -- Code analysis tools provided to AI agents. Tool execution involves file I/O. Inefficient tool implementations slow down the entire agentic loop.
- `src/generators/documentation/codebaseMapGenerator.ts` -- Generates a structural map of the codebase. For large repos, this can be slow due to directory traversal.
- `src/services/quickSync/quickSyncService.ts` -- QuickSync provides a faster alternative to full sync. Understanding its optimizations helps when optimizing other services.
- `src/index.ts` -- CLI startup imports all services eagerly. Startup time is affected by import chain depth.

## Workflow Steps

1. **Profile the operation**: Identify which CLI command is slow. Run with `--verbose` flag and observe timing. Key operations to profile:
   - `context({ action: "init" })` -- File scanning + scaffold generation
   - `context({ action: "fill" })` / `fillSingle` -- Semantic context assembly per scaffold file
   - `dotcontext sync` -- File discovery + symlink/reference creation
   - `dotcontext report` -- File scanning + frontmatter parsing

2. **Measure file I/O**: FileMapper and glob operations are the most common bottleneck. Check:
   - Are exclude patterns in `globPatterns.ts` covering all irrelevant directories?
   - Is the `glob` package (v10) being called with `{ ignore }` option rather than post-filtering?
   - Are files being read multiple times? (frontmatter parsing reads file headers; fill reads full content)

3. **Analyze context size**: For scaffold fill operations, check:
   - Shared semantic context size returned by `fillScaffoldingTool`
   - Whether repeated `fillSingle` calls rebuild or bypass cached context
   - Whether a narrower `target` or lower `limit` would reduce MCP response size

4. **Check tree-sitter parsing**: `CodebaseAnalyzer` defaults to parsing up to 5000 files. For large repos:
   - Verify language filtering is applied early (only parse files matching requested languages).
   - Check if caching is enabled (`cacheEnabled: true` in options).
   - Consider whether the `useLSP` flag is enabled unnecessarily (LSP adds significant overhead).

5. **Implement the optimization**: Common strategies:
   - **Lazy imports**: Move heavy imports (tree-sitter, AI SDK) to dynamic `import()` inside the functions that need them, reducing startup time.
   - **Parallel processing**: Use `Promise.all()` for independent file operations where the MCP response model still stays bounded.
   - **Streaming**: Use `createReadStream` with readline (already used in `frontMatter.ts` for fast status detection) instead of full `fs.readFile()` where only headers are needed.
   - **Caching**: Cache parsed frontmatter, file maps, and semantic analysis results between commands.

6. **Verify with benchmarks**: Run before/after on a representative large repository. Measure wall-clock time and peak memory usage.

## Best Practices

- **Profile before optimizing**: Use `--verbose` output and `console.time()`/`console.timeEnd()` to identify actual bottlenecks rather than guessing.
- **Respect the `maxFiles` limit**: `CodebaseAnalyzer` has a 5000-file cap for good reason. Do not remove it; instead, improve filtering so the right 5000 files are analyzed.
- **Use streaming frontmatter reads**: `src/utils/frontMatter.ts` already has optimized first-line reading for fast status detection. Extend this pattern for any operation that only needs file metadata.
- **Token-efficient context**: When building context for LLM calls, use `serializeStructureForAI()` which produces a compact representation rather than sending full file contents.
- **Avoid synchronous fs calls**: The codebase uses `fs-extra` (async) consistently. Never introduce synchronous file operations (`fs.readFileSync`, etc.) as they block the event loop and degrade perceived CLI responsiveness.

## Common Pitfalls

- **Premature parallelization of scaffold work**: Running too many semantic-analysis tasks in parallel can spike memory and produce oversized MCP payloads. Use a concurrency limiter rather than unbounded `Promise.all()`.
- **Tree-sitter memory leaks**: Tree-sitter parsers hold native memory. If parsing thousands of files, ensure parsers are reused (not re-created per file) and that parse trees are released after symbol extraction.
- **Glob pattern order matters**: The `glob` package evaluates patterns in order. Put the most selective patterns first to short-circuit directory traversal early.
- **Over-caching stale data**: If implementing caching, include file modification timestamps or git commit hashes as cache keys. Stale caches cause incorrect scaffold content or missing files.
- **Ignoring the QuickSync model**: `QuickSyncService` already implements optimized file discovery. Before building custom optimizations for other services, study its approach to reuse patterns.


================================================
FILE: .context/agents/refactoring-specialist.md
================================================
---
type: agent
name: refactoring-specialist
description: Identify code smells and improvement opportunities
role: developer
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Refactoring Specialist

## Role

Identify code smells, architectural inconsistencies, and improvement opportunities in the dotcontext codebase. Refactoring targets include: reducing coupling between services, standardizing patterns across generators, consolidating duplicated logic into shared utilities, improving type safety, and simplifying the service dependency injection model.

## Key Files to Understand

- `src/index.ts` -- CLI entry point. Currently houses all command registration and service instantiation inline. A primary refactoring candidate for command registration extraction.
- `src/services/mcp/gateway/context.ts` -- Consolidates multiple scaffold and semantic-context actions behind one gateway. It is a high-impact refactoring surface because multiple MCP flows converge here.
- `src/generators/agents/agentGenerator.ts` -- Second most imported (13 dependents). Contains the `AGENT_PHASES` mapping, agent generation logic, and semantic context integration. Consider extracting the phase mapping to the workflow module.
- `src/services/shared/` -- Shared utilities directory with path helpers, glob patterns, content type registry, context root resolution, UI helpers, and tool registry. Some services duplicate logic that could be centralized here.
- `src/generators/shared/` -- Shared generator code including `scaffoldStructures.ts`, `generatorUtils.ts`, `contextGenerator.ts`, and the `structures/` registry. The structures system is well-designed but some generators bypass it.
- `src/workflow/` -- PREVC workflow module with phases, roles, gates, orchestration, scaling, status management, and skills. Internal cohesion is good but the API surface to external consumers could be cleaner.
- `src/services/ai/providerFactory.ts` -- AI provider abstraction. Four providers (openrouter, openai, anthropic, google) with similar setup patterns that could benefit from a strategy pattern.
- `src/utils/frontMatter.ts` -- Handles both v1 and v2 frontmatter formats. The dual-format support adds complexity; consider a unified parser with format auto-detection.
- `src/types.ts` -- Global types file. Some interfaces here are only used by specific services and could be co-located.
- `src/services/init/initService.ts`, `src/services/sync/syncService.ts`, `src/services/workflow/workflowService.ts` -- Strong reference implementations for the current service pattern.

## Workflow Steps

1. **Audit the dependency graph**: Identify high fan-in (many importers) and high fan-out (many imports) modules. Key metrics:
   - `handleContext` and `fillScaffoldingTool`: high fan-in around MCP scaffolding flows
   - `AgentGenerator`: 13 importers -- the `AGENT_PHASES` constant could live in `src/workflow/` instead
   - `InitService`: 9 importers

2. **Identify pattern violations**: The standard service pattern is:
   - `Constructor(dependencies: ServiceDependencies)` -> `resolveOptions(flags)` -> `validate()` -> `execute()` -> UI feedback
   - Find services that deviate: missing dependency injection, direct console.log instead of `ui.*`, hardcoded paths instead of using `contextRootResolver`, or synchronous operations where async is expected.

3. **Find duplicated logic**: Common duplication areas:
   - Frontmatter reading/writing across services (should all use `src/utils/frontMatter.ts`)
   - Glob pattern assembly (should all use `src/services/shared/globPatterns.ts`)
   - Provider/default-model detection (should consistently use `src/services/ai/providerFactory.ts` and `src/utils/prompts/smartDefaults.ts`)
   - File discovery patterns (scanning `.context/` subdirectories)

4. **Plan the refactoring**: For each identified improvement:
   - Assess the blast radius (how many files change)
   - Determine if it can be done incrementally (extract interface first, then migrate callers)
   - Check test coverage of affected code before refactoring

5. **Execute incrementally**: Make one structural change at a time. After each change:
   - Run `npm run build` to verify type safety
   - Run `npm test` to verify behavior
   - Verify barrel exports in `index.ts` files are updated

6. **Update scaffolds and structures**: If refactoring changes public APIs of services or generators, update the corresponding scaffold structures in `src/generators/shared/structures/` and templates so future MCP `context({ action: "init" })` runs produce correct scaffolds.

## Best Practices

- **Extract, don't rewrite**: Move existing code into better locations rather than rewriting from scratch. This preserves tested behavior.
- **Maintain barrel exports**: Every directory's `index.ts` must be updated when files are added, removed, or renamed. External consumers import from barrels.
- **Keep the dependency injection contract**: Services accept `{ ui, t, version, ... }` in constructors. When extracting sub-services, give them their own dependency interface rather than passing the parent's full dependency object.
- **Use TypeScript's type system**: When splitting interfaces, use `Pick<>`, `Omit<>`, and intersection types to derive sub-interfaces from existing ones. This keeps types DRY and ensures compatibility.
- **Preserve the PREVC model**: The workflow phases (Planning, Review, Execution, Validation, Confirmation) and roles (planner, designer, architect, developer, qa, reviewer, documenter, solo-dev) are core architectural concepts. Refactoring should make these clearer, not obscure them.

## Common Pitfalls

- **Breaking circular dependencies**: The codebase has some circular import risks between `generators/agents` <-> `services/autoFill` <-> `services/stack`. Use dependency inversion (interfaces in shared modules) to break cycles rather than restructuring entire directories.
- **Over-abstracting the AI layer**: The four LLM providers have genuinely different capabilities (tool calling support, structured output, streaming). Do not force them into an overly uniform interface that hides important differences.
- **Losing i18n coverage**: When moving user-facing code between files, ensure translation key usage (`t('key')`) follows the code. Orphaned translation keys and missing translations are hard to detect.
- **Scaffold version compatibility**: The codebase supports both v1 and v2 frontmatter. Refactoring frontmatter handling must preserve backward compatibility -- users have existing `.context/` directories with v1 files.
- **Large PRs**: Resist the temptation to refactor everything at once. Each refactoring PR should touch one concern (e.g., "extract command registration from index.ts" or "consolidate glob pattern handling"). This makes review feasible and rollback safe.


================================================
FILE: .context/agents/test-writer.md
================================================
---
type: agent
name: test-writer
description: Write comprehensive unit and integration tests
role: qa
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Test Writer

## Role

Write and maintain unit and integration tests for the dotcontext project using Jest with ts-jest. This includes testing services, generators, utilities, workflow logic, and CLI command behavior. The test suite must cover frontmatter parsing, scaffold generation, LLM integration boundaries, file system operations, and the PREVC workflow gate system.

## Key Files to Understand

- `jest.config.js` -- Jest configuration: `ts-jest` preset, roots in `src/`, test patterns `**/__tests__/**/*.ts` and `**/?(*.)+(spec|test).ts`, coverage from `src/**/*.ts` excluding `.d.ts` and `index.ts` files.
- `tsconfig.json` -- TypeScript strict mode, target ES2020, commonjs modules. Tests are excluded from compilation (`**/*.test.ts` in exclude array) but ts-jest handles them at runtime.
- `src/utils/frontMatter.test.ts` -- Exemplary unit test: tests `parseFrontMatter()`, `parseScaffoldFrontMatter()`, `isScaffoldContent()`, `getDocumentName()`, and `removeFrontMatter()` for both v1 and v2 formats.
- `src/utils/contentSanitizer.test.ts` -- Tests the `sanitizeAIResponse()` function that cleans LLM output. Good example of edge-case-driven testing.
- `src/utils/versionChecker.test.ts` -- Tests the npm version checking utility with mocked HTTP calls.
- `src/utils/promptLoader.test.ts` -- Tests prompt file loading and resolution.
- `src/generators/agents/agentGenerator.test.ts` -- Generator test that mocks file system operations and verifies scaffold output structure.
- `src/generators/plans/planGenerator.test.ts` -- Plan generator test with similar mocking patterns.
- `src/generators/documentation/documentationGenerator.test.ts` -- Documentation generator test.
- `src/workflow/gates/gateChecker.test.ts` -- Tests PREVC phase gate validation logic. Good example of testing state machine transitions.
- `src/services/semantic/codebaseAnalyzer.test.ts` -- Tests tree-sitter integration with actual parsing. Demonstrates handling optional native dependencies in tests.
- `src/services/shared/__tests__/contextRootResolver.test.ts` -- Service test in `__tests__/` directory structure.
- `src/cli.test.ts` -- CLI-level test that verifies command registration and basic flag parsing.
- `src/services/mcp/mcpServer.test.ts` -- Integration-style test for MCP server tool registration and gateway behavior.

## Workflow Steps

1. **Identify untested code**: Run `npm test -- --coverage` to generate a coverage report. Look at `coverage/lcov-report/index.html` for visual coverage gaps. Priority areas with low coverage:
   - Service `run()` methods (complex orchestration logic)
   - MCP gateway handlers and scaffold tools
   - Workflow orchestration and status management
   - CLI command handlers in `src/index.ts`

2. **Choose test location**: Use one of two patterns:
   - Co-located: `src/services/mcp/mcpInstallService.test.ts` (next to the source file)
   - Directory: `src/services/shared/__tests__/contextRootResolver.test.ts` (in `__tests__/` subdirectory)

   Both patterns are matched by Jest config. Prefer co-located for single-file tests and `__tests__/` for multi-file test suites.

3. **Set up mocks**: Common mocking patterns in this codebase:

   **CLIInterface mock**:
   ```typescript
   const mockUI = {
     displayWelcome: jest.fn(),
     startSpinner: jest.fn(),
     stopSpinner: jest.fn(),
     displaySuccess: jest.fn(),
     displayError: jest.fn(),
     displayInfo: jest.fn(),
     displayWarning: jest.fn(),
   } as unknown as CLIInterface;
   ```

   **TranslateFn mock**:
   ```typescript
   const mockT: TranslateFn = ((key: string) => key) as TranslateFn;
   ```

   **fs-extra mock**:
   ```typescript
   jest.mock('fs-extra', () => ({
     ensureDir: jest.fn(),
     writeFile: jest.fn(),
     readFile: jest.fn(),
     pathExists: jest.fn().mockResolvedValue(true),
     readdir: jest.fn().mockResolvedValue([]),
   }));
   ```

   **LLM client mock** (for AI service tests):
   ```typescript
   jest.mock('ai', () => ({
     generateText: jest.fn().mockResolvedValue({ text: 'mocked response', steps: [] }),
     generateObject: jest.fn().mockResolvedValue({ object: {} }),
   }));
   ```

4. **Write the test**: Follow the Arrange-Act-Assert pattern. Group related tests with `describe()` blocks matching the class or function name. Use descriptive `it()` strings that state the expected behavior.

5. **Test frontmatter handling**: For any test involving `.context/` files, include both v1 and v2 frontmatter cases:
   ```typescript
   // v1 frontmatter
   const v1Content = '---\nstatus: unfilled\ngenerated: 2026-01-01\n---\n# Content';

   // v2 scaffold frontmatter
   const v2Content = '---\ntype: doc\nname: overview\ndescription: Project overview\ngenerated: 2026-01-01\nstatus: unfilled\nscaffoldVersion: "2.0.0"\n---\n# Content';
   ```

6. **Run and verify**: Execute `npm test` for the full suite or `npm test -- --testPathPattern=<pattern>` for specific tests. Check that coverage does not regress.

## Best Practices

- **Mock at boundaries, not internals**: Mock `fs-extra`, `glob`, HTTP clients, and the AI SDK. Do not mock internal service methods -- test them through the public API.
- **Test the service contract**: Services accept flags and produce side effects (file writes, console output). Test that given specific flags, the correct files are written with correct content and the UI methods are called in the right order.
- **Use `jest.spyOn()` for partial mocking**: When testing a service that calls another service, spy on the dependent service's methods rather than replacing the entire module.
- **Handle optional dependencies**: `tree-sitter` is optional. Tests for `CodebaseAnalyzer` should have a setup that skips tests if tree-sitter is not installed:
   ```typescript
   let treeSitterAvailable = true;
   try { require('tree-sitter'); } catch { treeSitterAvailable = false; }
   const describeIfTreeSitter = treeSitterAvailable ? describe : describe.skip;
   ```
- **Test i18n key usage**: Verify that service code calls `t()` with valid keys by using the mock `TranslateFn` that returns the key string, then asserting the key was passed to UI methods.

## Common Pitfalls

- **Forgetting `await` in tests**: Many service methods are async. Forgetting `await` on the method call causes the test to pass before assertions are evaluated. Always `await` async operations and use `expect(...).resolves` or `expect(...).rejects` for promise assertions.
- **File system state leakage**: Tests that write to actual files or temp directories must clean up in `afterEach()` or `afterAll()`. Use `os.tmpdir()` and unique directory names.
- **Mocking module-level constants**: Some modules export constants at the module level (e.g., `AGENT_TYPES`, `PREVC_PHASE_ORDER`). These cannot be mocked with `jest.mock()` easily. Import them directly and test code that uses them.
- **Snapshot fragility**: Avoid snapshot tests for generated markdown content -- they break on any formatting change. Instead, assert on structural properties (frontmatter fields present, section headings exist, file count correct).
- **Testing LLM output**: Never test actual LLM responses in unit tests. Mock the AI SDK and test that the correct prompts and parameters are passed. Integration tests with real LLM calls should be separate and marked with a custom Jest tag or environment variable check.


================================================
FILE: .context/docs/README.md
================================================
# Documentation Index

Welcome to the `@dotcontext/cli` repository knowledge base. Start with the project overview, then dive into specific guides as needed.

## Core Guides

| Guide | File | Primary Inputs |
| --- | --- | --- |
| Project Overview | [`project-overview.md`](./project-overview.md) | Roadmap, README, stakeholder notes |
| Development Workflow | [`development-workflow.md`](./development-workflow.md) | Branching rules, CI config, contributing guide |
| Testing Strategy | [`testing-strategy.md`](./testing-strategy.md) | Test configs, CI gates, known flaky suites |
| Tooling & Productivity | [`tooling.md`](./tooling.md) | CLI scripts, IDE configs, automation workflows |
| Harness Split Foundation | [`harness-split-foundation.md`](./harness-split-foundation.md) | Branch changes, package boundary decisions, harness engineering alignment |
| Harness Roadmap | [`harness-roadmap.md`](./harness-roadmap.md) | Harness engineering capabilities, sequencing, and product direction |

## Q&A

Frequently asked questions are organized by topic in the [`qa/`](./qa/) directory.
See [qa/README.md](./qa/README.md) for the full index.

## Codebase Map

Machine-readable project structure and stack metadata: [`codebase-map.json`](./codebase-map.json)

## Repository Snapshot

```
AGENTS.md
CHANGELOG.md
CLAUDE.md
CONTRIBUTING.md
LICENSE
README.md
docs/             -- Published documentation produced by this tool
example-documentation.ts
jest.config.js
package.json
package-lock.json
prompts/          -- Prompt templates (update_plan_prompt.md, update_scaffold_prompt.md)
scripts/          -- Build and test helper scripts
src/              -- TypeScript source (~240 files): CLI entrypoint, services, generators, utilities
tsconfig.json
```


================================================
FILE: .context/docs/codebase-map.json
================================================
{
  "version": "1.0.0",
  "generated": "2026-03-18T21:32:49.263Z",
  "stack": {
    "primaryLanguage": "typescript",
    "languages": [
      "javascript",
      "typescript"
    ],
    "frameworks": [],
    "buildTools": [],
    "testFrameworks": [
      "jest"
    ],
    "packageManager": "npm",
    "isMonorepo": false,
    "hasDocker": false,
    "hasCI": true,
    "nodeVersion": ">=20.0.0",
    "runtimeEnvironment": "node"
  },
  "structure": {
    "totalFiles": 255,
    "rootPath": ".",
    "topDirectories": [
      {
        "name": "docs",
        "fileCount": 1,
        "description": "Documentation files"
      },
      {
        "name": "prompts",
        "fileCount": 2,
        "description": "Prompt templates"
      },
      {
        "name": "scripts",
        "fileCount": 1,
        "description": "Build and utility scripts"
      },
      {
        "name": "src",
        "fileCount": 240,
        "description": "Source code root"
      }
    ],
    "languageDistribution": [
      {
        "extension": ".ts",
        "count": 240
      },
      {
        "extension": ".md",
        "count": 9
      },
      {
        "extension": ".json",
        "count": 3
      },
      {
        "extension": ".js",
        "count": 2
      }
    ]
  },
  "architecture": {
    "layers": [
      {
        "name": "Config",
        "description": "Configuration and constants",
        "directories": [
          "src/workflow",
          "."
        ],
        "symbolCount": 4,
        "dependsOn": []
      },
      {
        "name": "Utils",
        "description": "Shared utilities and helpers",
        "directories": [
          "src/utils",
          "src/utils/prompts",
          "src/generators/shared",
          "src/generators/shared/structures",
          "src/generators/documentation/templates",
          "src/generators/shared/structures/skills",
          "src/generators/shared/structures/plans",
          "src/generators/shared/structures/documentation",
          "src/generators/shared/structures/agents"
        ],
        "symbolCount": 84,
        "dependsOn": [
          "Services",
          "Generators"
        ]
      },
      {
        "name": "Services",
        "description": "Business logic and orchestration",
        "directories": [
          "src/utils",
          "src/services",
          "src/services/workflow",
          "src/services/update",
          "src/services/sync",
          "src/services/state",
          "src/services/start",
          "src/services/stack",
          "src/services/shared",
          "src/services/serve",
          "src/services/semantic",
          "src/services/reverseSync",
          "src/services/report",
          "src/services/quickSync",
          "src/services/qa",
          "src/services/plan",
          "src/services/passthrough",
          "src/services/mcp",
          "src/services/init",
          "src/services/import",
          "src/services/fill",
          "src/services/export",
          "src/services/autoFill",
          "src/services/ai",
          "src/services/shared/__tests__",
          "src/services/semantic/treeSitter",
          "src/services/semantic/lsp",
          "src/services/mcp/gateway",
          "src/services/ai/tools",
          "src/services/ai/prompts",
          "src/services/ai/agents"
        ],
        "symbolCount": 475,
        "dependsOn": [
          "Config",
          "Generators",
          "Utils"
        ]
      },
      {
        "name": "Generators",
        "description": "Content and object generation",
        "directories": [
          "src/generators/skills",
          "src/generators/plans",
          "src/generators/documentation",
          "src/generators/agents",
          "src/generators/skills/templates",
          "src/generators/plans/templates",
          "src/generators/documentation/templates",
          "src/generators/agents/templates"
        ],
        "symbolCount": 51,
        "dependsOn": [
          "Config",
          "Utils",
          "Services"
        ]
      }
    ],
    "patterns": [
      {
        "name": "Factory",
        "confidence": 0.9,
        "description": "Creates instances of related objects without specifying concrete classes",
        "occurrences": 1
      },
      {
        "name": "Service Layer",
        "confidence": 0.85,
        "description": "Encapsulates business logic in service classes",
        "occurrences": 22
      },
      {
        "name": "Builder",
        "confidence": 0.85,
        "description": "Separates object construction from its representation",
        "occurrences": 1
      }
    ],
    "entryPoints": [
      "src/index.ts",
      "src/workflow/index.ts",
      "src/workflow/skills/index.ts",
      "src/workflow/plans/index.ts",
      "src/workflow/orchestration/index.ts",
      "src/workflow/gates/index.ts",
      "src/workflow/agents/index.ts",
      "src/utils/prompts/index.ts",
      "src/services/workflow/index.ts",
      "src/services/update/index.ts",
      "src/services/sync/index.ts",
      "src/services/state/index.ts",
      "src/services/start/index.ts",
      "src/services/stack/index.ts",
      "src/services/shared/index.ts",
      "src/services/serve/index.ts",
      "src/services/semantic/index.ts",
      "src/services/reverseSync/index.ts",
      "src/services/report/index.ts",
      "src/services/quickSync/index.ts",
      "src/services/qa/index.ts",
      "src/services/passthrough/index.ts",
      "src/services/mcp/index.ts",
      "src/services/import/index.ts",
      "src/services/export/index.ts",
      "src/services/autoFill/index.ts",
      "src/services/ai/index.ts",
      "src/generators/skills/index.ts",
      "src/generators/shared/index.ts",
      "src/generators/plans/index.ts",
      "src/generators/documentation/index.ts",
      "src/generators/agents/index.ts",
      "src/services/semantic/treeSitter/index.ts",
      "src/services/semantic/lsp/index.ts",
      "src/services/mcp/gateway/index.ts",
      "src/services/ai/tools/index.ts",
      "src/services/ai/prompts/index.ts",
      "src/services/ai/agents/index.ts",
      "src/generators/shared/structures/index.ts",
      "src/generators/documentation/templates/index.ts",
      "src/generators/agents/templates/index.ts",
      "src/generators/shared/structures/skills/index.ts",
      "src/generators/shared/structures/plans/index.ts",
      "src/generators/shared/structures/documentation/index.ts",
      "src/generators/shared/structures/agents/index.ts"
    ],
    "mainEntryPoints": [
      "src/index.ts"
    ],
    "moduleExports": [
      "src/workflow/index.ts",
      "src/workflow/skills/index.ts",
      "src/workflow/plans/index.ts",
      "src/workflow/orchestration/index.ts",
      "src/workflow/gates/index.ts",
      "src/workflow/agents/index.ts",
      "src/utils/prompts/index.ts",
      "src/services/workflow/index.ts",
      "src/services/update/index.ts",
      "src/services/sync/index.ts",
      "src/services/state/index.ts",
      "src/services/start/index.ts",
      "src/services/stack/index.ts",
      "src/services/shared/index.ts",
      "src/services/serve/index.ts",
      "src/services/semantic/index.ts",
      "src/services/reverseSync/index.ts",
      "src/services/report/index.ts",
      "src/services/quickSync/index.ts",
      "src/services/qa/index.ts",
      "src/services/passthrough/index.ts",
      "src/services/mcp/index.ts",
      "src/services/import/index.ts",
      "src/services/export/index.ts",
      "src/services/autoFill/index.ts",
      "src/services/ai/index.ts",
      "src/generators/skills/index.ts",
      "src/generators/shared/index.ts",
      "src/generators/plans/index.ts",
      "src/generators/documentation/index.ts",
      "src/generators/agents/index.ts",
      "src/services/semantic/treeSitter/index.ts",
      "src/services/semantic/lsp/index.ts",
      "src/services/mcp/gateway/index.ts",
      "src/services/ai/tools/index.ts",
      "src/services/ai/prompts/index.ts",
      "src/services/ai/agents/index.ts",
      "src/generators/shared/structures/index.ts",
      "src/generators/documentation/templates/index.ts",
      "src/generators/agents/templates/index.ts",
      "src/generators/shared/structures/skills/index.ts",
      "src/generators/shared/structures/plans/index.ts",
      "src/generators/shared/structures/documentation/index.ts",
      "src/generators/shared/structures/agents/index.ts"
    ]
  },
  "symbols": {
    "classes": [
      {
        "name": "AgentGenerator",
        "kind": "class",
        "file": "src/generators/agents/agentGenerator.ts",
        "line": 65,
        "exported": true
      },
      {
        "name": "AgentOrchestrator",
        "kind": "class",
        "file": "src/workflow/orchestration/agentOrchestrator.ts",
        "line": 168,
        "exported": true
      },
      {
        "name": "AgentRegistry",
        "kind": "class",
        "file": "src/workflow/agents/agentRegistry.ts",
        "line": 67,
        "exported": true
      },
      {
        "name": "AgentsDetector",
        "kind": "class",
        "file": "src/services/import/agentsDetector.ts",
        "line": 7,
        "exported": true
      },
      {
        "name": "AISdkClient",
        "kind": "class",
        "file": "src/services/ai/aiSdkClient.ts",
        "line": 8,
        "exported": true
      },
      {
        "name": "AutoAdvanceDetector",
        "kind": "class",
        "file": "src/services/workflow/autoAdvance.ts",
        "line": 78,
        "exported": true
      },
      {
        "name": "AutoFillService",
        "kind": "class",
        "file": "src/services/autoFill/autoFillService.ts",
        "line": 26,
        "exported": true
      },
      {
        "name": "CLIInterface",
        "kind": "class",
        "file": "src/utils/cliUI.ts",
        "line": 15,
        "exported": true
      },
      {
        "name": "CodebaseMapGenerator",
        "kind": "class",
        "file": "src/generators/documentation/codebaseMapGenerator.ts",
        "line": 192,
        "exported": true
      },
      {
        "name": "CollaborationManager",
        "kind": "class",
        "file": "src/workflow/collaboration.ts",
        "line": 325,
        "exported": true
      },
      {
        "name": "CollaborationSession",
        "kind": "class",
        "file": "src/workflow/collaboration.ts",
        "line": 29,
        "exported": true
      },
      {
        "name": "CommandRouter",
        "kind": "class",
        "file": "src/services/passthrough/commandRouter.ts",
        "line": 114,
        "exported": true
      },
      {
        "name": "ContextExportService",
        "kind": "class",
        "file": "src/services/export/contextExportService.ts",
        "line": 51,
        "exported": true
      },
      {
        "name": "ContextGenerator",
        "kind": "class",
        "file": "src/generators/shared/contextGenerator.ts",
        "line": 3,
        "exported": true
      },
      {
        "name": "DocumentationAgent",
        "kind": "class",
        "file": "src/services/ai/agents/documentationAgent.ts",
        "line": 38,
        "exported": true
      },
      {
        "name": "DocumentationGenerator",
        "kind": "class",
        "file": "src/generators/documentation/documentationGenerator.ts",
        "line": 63,
        "exported": true
      },
      {
        "name": "DocumentLinker",
        "kind": "class",
        "file": "src/workflow/orchestration/documentLinker.ts",
        "line": 150,
        "exported": true
      },
      {
        "name": "ExportRulesService",
        "kind": "class",
        "file": "src/services/export/exportRulesService.ts",
        "line": 93,
        "exported": true
      },
      {
        "name": "FileMapper",
        "kind": "class",
        "file": "src/utils/fileMapper.ts",
        "line": 6,
        "exported": true
      },
      {
        "name": "FillService",
        "kind": "class",
        "file": "src/services/fill/fillService.ts",
        "line": 92,
        "exported": true
      },
      {
        "name": "GeneratorUtils",
        "kind": "class",
        "file": "src/generators/shared/generatorUtils.ts",
        "line": 6,
        "exported": true
      },
      {
        "name": "GitService",
        "kind": "class",
        "file": "src/utils/gitService.ts",
        "line": 24,
        "exported": true
      },
      {
        "name": "ImportAgentsService",
        "kind": "class",
        "file": "src/services/import/importAgentsService.ts",
        "line": 16,
        "exported": true
      },
      {
        "name": "ImportRulesService",
        "kind": "class",
        "file": "src/services/import/importRulesService.ts",
        "line": 17,
        "exported": true
      },
      {
        "name": "ImportSkillsService",
        "kind": "class",
        "file": "src/services/reverseSync/importSkillsService.ts",
        "line": 41,
        "exported": true
      },
      {
        "name": "InitService",
        "kind": "class",
        "file": "src/services/init/initService.ts",
        "line": 52,
        "exported": true
      },
      {
        "name": "LLMClientFactory",
        "kind": "class",
        "file": "src/services/llmClientFactory.ts",
        "line": 12,
        "exported": true
      },
      {
        "name": "LSPLayer",
        "kind": "class",
        "file": "src/services/semantic/lsp/lspLayer.ts",
        "line": 53,
        "exported": true
      },
      {
        "name": "MCPInstallService",
        "kind": "class",
        "file": "src/services/mcp/mcpInstallService.ts",
        "line": 416,
        "exported": true
      },
      {
        "name": "NoPlanToApproveError",
        "kind": "class",
        "file": "src/workflow/errors.ts",
        "line": 47,
        "exported": true
      }
    ],
    "interfaces": [
      {
        "name": "AffectedDoc",
        "kind": "interface",
        "file": "src/services/update/updateService.ts",
        "line": 31,
        "exported": true
      },
      {
        "name": "AgentCompleteEvent",
        "kind": "interface",
        "file": "src/services/ai/agentEvents.ts",
        "line": 31,
        "exported": true
      },
      {
        "name": "AgentDefaultContent",
        "kind": "interface",
        "file": "src/generators/shared/structures/agents/factory.ts",
        "line": 10,
        "exported": true
      },
      {
        "name": "AgentEventCallbacks",
        "kind": "interface",
        "file": "src/services/ai/agentEvents.ts",
        "line": 37,
        "exported": true
      },
      {
        "name": "AgentFileInfo",
        "kind": "interface",
        "file": "src/services/sync/types.ts",
        "line": 47,
        "exported": true
      },
      {
        "name": "AgentLineupEntry",
        "kind": "interface",
        "file": "src/workflow/plans/types.ts",
        "line": 137,
        "exported": true
      },
      {
        "name": "AgentMetadata",
        "kind": "interface",
        "file": "src/workflow/agents/agentRegistry.ts",
        "line": 36,
        "exported": true
      },
      {
        "name": "AgentOptions",
        "kind": "interface",
        "file": "src/services/mcp/gateway/agent.ts",
        "line": 23,
        "exported": true
      },
      {
        "name": "AgentParams",
        "kind": "interface",
        "file": "src/services/mcp/gateway/types.ts",
        "line": 113,
        "exported": true
      },
      {
        "name": "AgentPrompt",
        "kind": "interface",
        "file": "src/types.ts",
        "line": 48,
        "exported": true
      },
      {
        "name": "AgentScaffoldFrontmatter",
        "kind": "interface",
        "file": "src/types/scaffoldFrontmatter.ts",
        "line": 51,
        "exported": true
      },
      {
        "name": "AgentSequenceStep",
        "kind": "interface",
        "file": "src/workflow/types.ts",
        "line": 320,
        "exported": true
      },
      {
        "name": "AgentStartEvent",
        "kind": "interface",
        "file": "src/services/ai/agentEvents.ts",
        "line": 7,
        "exported": true
      },
      {
        "name": "AgentStatus",
        "kind": "interface",
        "file": "src/workflow/types.ts",
        "line": 114,
        "exported": true
      },
      {
        "name": "AgentStepEvent",
        "kind": "interface",
        "file": "src/services/ai/agentEvents.ts",
        "line": 12,
        "exported": true
      },
      {
        "name": "AgentTemplateContext",
        "kind": "interface",
        "file": "src/generators/agents/templates/types.ts",
        "line": 16,
        "exported": true
      },
      {
        "name": "AgentUpdate",
        "kind": "interface",
        "file": "src/workflow/types.ts",
        "line": 281,
        "exported": true
      },
      {
        "name": "AIDependencies",
        "kind": "interface",
        "file": "src/services/shared/types.ts",
        "line": 23,
        "exported": true
      },
      {
        "name": "AnalysisOptions",
        "kind": "interface",
        "file": "src/utils/prompts/types.ts",
        "line": 38,
        "exported": true
      },
      {
        "name": "AnalyzerOptions",
        "kind": "interface",
        "file": "src/services/semantic/types.ts",
        "line": 187,
        "exported": true
      },
      {
        "name": "ArchitectureInfo",
        "kind": "interface",
        "file": "src/services/semantic/types.ts",
        "line": 147,
        "exported": true
      },
      {
        "name": "ArchitectureLayer",
        "kind": "interface",
        "file": "src/services/semantic/types.ts",
        "line": 60,
        "exported": true
      },
      {
        "name": "AutoAdvanceResult",
        "kind": "interface",
        "file": "src/services/workflow/autoAdvance.ts",
        "line": 16,
        "exported": true
      },
      {
        "name": "AutoFillContext",
        "kind": "interface",
        "file": "src/services/autoFill/autoFillService.ts",
        "line": 14,
        "exported": true
      },
      {
        "name": "BaseDependencies",
        "kind": "interface",
        "file": "src/services/shared/types.ts",
        "line": 14,
        "exported": true
      },
      {
        "name": "BaseScaffoldFrontmatter",
        "kind": "interface",
        "file": "src/types/scaffoldFrontmatter.ts",
        "line": 24,
        "exported": true
      },
      {
        "name": "CapabilitiesData",
        "kind": "interface",
        "file": "src/services/passthrough/protocol.ts",
        "line": 198,
        "exported": true
      },
      {
        "name": "CLIOptions",
        "kind": "interface",
        "file": "src/types.ts",
        "line": 34,
        "exported": true
      },
      {
        "name": "CodebaseMap",
        "kind": "interface",
        "file": "src/generators/documentation/codebaseMapGenerator.ts",
        "line": 40,
        "exported": true
      },
      {
        "name": "CodebaseMapOptions",
        "kind": "interface",
        "file": "src/generators/documentation/codebaseMapGenerator.ts",
        "line": 108,
        "exported": true
      }
    ],
    "functions": [
      {
        "name": "addError",
        "kind": "function",
        "file": "src/services/shared/types.ts",
        "line": 101,
        "exported": true
      },
      {
        "name": "addFrontMatter",
        "kind": "function",
        "file": "src/utils/frontMatter.ts",
        "line": 124,
        "exported": true
      },
      {
        "name": "buildDocumentMapTable",
        "kind": "function",
        "file": "src/generators/documentation/templates/common.ts",
        "line": 57,
        "exported": true
      },
      {
        "name": "buildExtensionPattern",
        "kind": "function",
        "file": "src/services/shared/globPatterns.ts",
        "line": 124,
        "exported": true
      },
      {
        "name": "buildSymbolList",
        "kind": "function",
        "file": "src/generators/documentation/templates/common.ts",
        "line": 168,
        "exported": true
      },
      {
        "name": "buildSymbolTable",
        "kind": "function",
        "file": "src/generators/documentation/templates/common.ts",
        "line": 125,
        "exported": true
      },
      {
        "name": "checkForUpdates",
        "kind": "function",
        "file": "src/utils/versionChecker.ts",
        "line": 31,
        "exported": true
      },
      {
        "name": "checkSymlinkSupport",
        "kind": "function",
        "file": "src/services/sync/symlinkHandler.ts",
        "line": 83,
        "exported": true
      },
      {
        "name": "classifyProject",
        "kind": "function",
        "file": "src/services/stack/projectTypeClassifier.ts",
        "line": 122,
        "exported": true
      },
      {
        "name": "cleanupSharedContext",
        "kind": "function",
        "file": "src/services/ai/tools/fillScaffoldingTool.ts",
        "line": 56,
        "exported": true
      },
      {
        "name": "createAgentFrontmatter",
        "kind": "function",
        "file": "src/types/scaffoldFrontmatter.ts",
        "line": 150,
        "exported": true
      },
      {
        "name": "createAgentRegistry",
        "kind": "function",
        "file": "src/workflow/agents/agentRegistry.ts",
        "line": 220,
        "exported": true
      },
      {
        "name": "createAgentStructure",
        "kind": "function",
        "file": "src/generators/shared/structures/agents/factory.ts",
        "line": 44,
        "exported": true
      },
      {
        "name": "createBox",
        "kind": "function",
        "file": "src/services/shared/uiHelpers.ts",
        "line": 189,
        "exported": true
      },
      {
        "name": "createDocFrontmatter",
        "kind": "function",
        "file": "src/types/scaffoldFrontmatter.ts",
        "line": 131,
        "exported": true
      },
      {
        "name": "createEmptyResult",
        "kind": "function",
        "file": "src/services/shared/types.ts",
        "line": 74,
        "exported": true
      },
      {
        "name": "createErrorResponse",
        "kind": "function",
        "file": "src/services/passthrough/protocol.ts",
        "line": 218,
        "exported": true
      },
      {
        "name": "createErrorResponse",
        "kind": "function",
        "file": "src/services/mcp/gateway/response.ts",
        "line": 39,
        "exported": true
      },
      {
        "name": "createGateChecker",
        "kind": "function",
        "file": "src/workflow/gates/gateChecker.ts",
        "line": 252,
        "exported": true
      },
      {
        "name": "createInitialStatus",
        "kind": "function",
        "file": "src/workflow/status/templates.ts",
        "line": 97,
        "exported": true
      },
      {
        "name": "createJsonResponse",
        "kind": "function",
        "file": "src/services/mcp/gateway/response.ts",
        "line": 27,
        "exported": true
      },
      {
        "name": "createLargeProjectStatus",
        "kind": "function",
        "file": "src/workflow/status/templates.ts",
        "line": 192,
        "exported": true
      },
      {
        "name": "createMarkdownReferences",
        "kind": "function",
        "file": "src/services/sync/markdownReferenceHandler.ts",
        "line": 5,
        "exported": true
      },
      {
        "name": "createMediumProjectStatus",
        "kind": "function",
        "file": "src/workflow/status/templates.ts",
        "line": 180,
        "exported": true
      },
      {
        "name": "createPlanFrontmatter",
        "kind": "function",
        "file": "src/types/scaffoldFrontmatter.ts",
        "line": 198,
        "exported": true
      },
      {
        "name": "createProgressNotification",
        "kind": "function",
        "file": "src/services/passthrough/protocol.ts",
        "line": 234,
        "exported": true
      },
      {
        "name": "createProvider",
        "kind": "function",
        "file": "src/services/ai/providerFactory.ts",
        "line": 40,
        "exported": true
      },
      {
        "name": "createQuickFlowStatus",
        "kind": "function",
        "file": "src/workflow/status/templates.ts",
        "line": 156,
        "exported": true
      },
      {
        "name": "createQuickSyncService",
        "kind": "function",
        "file": "src/services/quickSync/quickSyncService.ts",
        "line": 300,
        "exported": true
      },
      {
        "name": "createReverseQuickSyncService",
        "kind": "function",
        "file": "src/services/reverseSync/reverseQuickSyncService.ts",
        "line": 288,
        "exported": true
      }
    ],
    "types": [
      {
        "name": "AgentAction",
        "kind": "type",
        "file": "src/services/mcp/gateway/types.ts",
        "line": 20,
        "exported": true
      },
      {
        "name": "AgentPlaybook",
        "kind": "type",
        "file": "src/services/ai/schemas.ts",
        "line": 439,
        "exported": true
      },
      {
        "name": "AgentRunRequest",
        "kind": "type",
        "file": "src/services/passthrough/protocol.ts",
        "line": 87,
        "exported": true
      },
      {
        "name": "AgentType",
        "kind": "type",
        "file": "src/workflow/orchestration/agentOrchestrator.ts",
        "line": 31,
        "exported": true
      },
      {
        "name": "AgentType",
        "kind": "type",
        "file": "src/services/ai/agentEvents.ts",
        "line": 5,
        "exported": true
      },
      {
        "name": "AgentType",
        "kind": "type",
        "file": "src/generators/agents/agentTypes.ts",
        "line": 18,
        "exported": true
      },
      {
        "name": "AIProvider",
        "kind": "type",
        "file": "src/types.ts",
        "line": 25,
        "exported": true
      },
      {
        "name": "AnalyzeSymbolsInput",
        "kind": "type",
        "file": "src/services/ai/schemas.ts",
        "line": 430,
        "exported": true
      },
      {
        "name": "AnalyzeSymbolsOutput",
        "kind": "type",
        "file": "src/services/ai/schemas.ts",
        "line": 431,
        "exported": true
      },
      {
        "name": "BaseRequest",
        "kind": "type",
        "file": "src/services/passthrough/protocol.ts",
        "line": 19,
        "exported": true
      },
      {
        "name": "BuiltInAgentType",
        "kind": "type",
        "file": "src/workflow/agents/agentRegistry.ts",
        "line": 31,
        "exported": true
      },
      {
        "name": "BuiltInSkillType",
        "kind": "type",
        "file": "src/workflow/skills/types.ts",
        "line": 81,
        "exported": true
      },
      {
        "name": "CapabilitiesRequest",
        "kind": "type",
        "file": "src/services/passthrough/protocol.ts",
        "line": 98,
        "exported": true
      },
      {
        "name": "CheckScaffoldingInput",
        "kind": "type",
        "file": "src/services/ai/schemas.ts",
        "line": 420,
        "exported": true
      },
      {
        "name": "CheckScaffoldingOutput",
        "kind": "type",
        "file": "src/services/ai/schemas.ts",
        "line": 421,
        "exported": true
      },
      {
        "name": "ContextAction",
        "kind": "type",
        "file": "src/services/mcp/gateway/types.ts",
        "line": 17,
        "exported": true
      },
      {
        "name": "ContextBuildRequest",
        "kind": "type",
        "file": "src/services/passthrough/protocol.ts",
        "line": 65,
        "exported": true
      },
      {
        "name": "ContextExportServiceDependencies",
        "kind": "type",
        "file": "src/services/export/contextExportService.ts",
        "line": 19,
        "exported": true
      },
      {
        "name": "ContextFormat",
        "kind": "type",
        "file": "src/services/semantic/contextBuilder.ts",
        "line": 30,
        "exported": true
      },
      {
        "name": "DevelopmentPlan",
        "kind": "type",
        "file": "src/services/ai/schemas.ts",
        "line": 440,
        "exported": true
      },
      {
        "name": "DocType",
        "kind": "type",
        "file": "src/workflow/orchestration/documentLinker.ts",
        "line": 14,
        "exported": true
      },
      {
        "name": "DocumentationOutput",
        "kind": "type",
        "file": "src/services/ai/schemas.ts",
        "line": 438,
        "exported": true
      },
      {
        "name": "ErrorCode",
        "kind": "type",
        "file": "src/services/passthrough/protocol.ts",
        "line": 284,
        "exported": true
      },
      {
        "name": "ExecutionAction",
        "kind": "type",
        "file": "src/workflow/types.ts",
        "line": 166,
        "exported": true
      },
      {
        "name": "ExploreAction",
        "kind": "type",
        "file": "src/services/mcp/gateway/types.ts",
        "line": 16,
        "exported": true
      },
      {
        "name": "ExportRulesServiceDependencies",
        "kind": "type",
        "file": "src/services/export/exportRulesService.ts",
        "line": 24,
        "exported": true
      },
      {
        "name": "FillScaffoldingInput",
        "kind": "type",
        "file": "src/services/ai/tools/fillScaffoldingTool.ts",
        "line": 265,
        "exported": true
      },
      {
        "name": "FillSingleFileInput",
        "kind": "type",
        "file": "src/services/ai/tools/fillScaffoldingTool.ts",
        "line": 177,
        "exported": true
      },
      {
        "name": "FunctionalPatternType",
        "kind": "type",
        "file": "src/services/semantic/types.ts",
        "line": 79,
        "exported": true
      },
      {
        "name": "GateType",
        "kind": "type",
        "file": "src/workflow/types.ts",
        "line": 145,
        "exported": true
      }
    ],
    "enums": [
      {
        "name": "ProjectScale",
        "kind": "enum",
        "file": "src/workflow/types.ts",
        "line": 33,
        "exported": true
      }
    ]
  },
  "publicAPI": [
    {
      "name": "addError",
      "kind": "function",
      "file": "src/services/shared/types.ts",
      "line": 101,
      "exported": true
    },
    {
      "name": "addFrontMatter",
      "kind": "function",
      "file": "src/utils/frontMatter.ts",
      "line": 124,
      "exported": true
    },
    {
      "name": "AffectedDoc",
      "kind": "interface",
      "file": "src/services/update/updateService.ts",
      "line": 31,
      "exported": true
    },
    {
      "name": "AgentAction",
      "kind": "type",
      "file": "src/services/mcp/gateway/types.ts",
      "line": 20,
      "exported": true
    },
    {
      "name": "AgentCompleteEvent",
      "kind": "interface",
      "file": "src/services/ai/agentEvents.ts",
      "line": 31,
      "exported": true
    },
    {
      "name": "AgentDefaultContent",
      "kind": "interface",
      "file": "src/generators/shared/structures/agents/factory.ts",
      "line": 10,
      "exported": true
    },
    {
      "name": "AgentEventCallbacks",
      "kind": "interface",
      "file": "src/services/ai/agentEvents.ts",
      "line": 37,
      "exported": true
    },
    {
      "name": "AgentFileInfo",
      "kind": "interface",
      "file": "src/services/sync/types.ts",
      "line": 47,
      "exported": true
    },
    {
      "name": "AgentGenerator",
      "kind": "class",
      "file": "src/generators/agents/agentGenerator.ts",
      "line": 65,
      "exported": true
    },
    {
      "name": "AgentLineupEntry",
      "kind": "interface",
      "file": "src/workflow/plans/types.ts",
      "line": 137,
      "exported": true
    },
    {
      "name": "AgentMetadata",
      "kind": "interface",
      "file": "src/workflow/agents/agentRegistry.ts",
      "line": 36,
      "exported": true
    },
    {
      "name": "AgentOptions",
      "kind": "interface",
      "file": "src/services/mcp/gateway/agent.ts",
      "line": 23,
      "exported": true
    },
    {
      "name": "AgentOrchestrator",
      "kind": "class",
      "file": "src/workflow/orchestration/agentOrchestrator.ts",
      "line": 168,
      "exported": true
    },
    {
      "name": "AgentParams",
      "kind": "interface",
      "file": "src/services/mcp/gateway/types.ts",
      "line": 113,
      "exported": true
    },
    {
      "name": "AgentPlaybook",
      "kind": "type",
      "file": "src/services/ai/schemas.ts",
      "line": 439,
      "exported": true
    },
    {
      "name": "AgentPrompt",
      "kind": "interface",
      "file": "src/types.ts",
      "line": 48,
      "exported": true
    },
    {
      "name": "AgentRegistry",
      "kind": "class",
      "file": "src/workflow/agents/agentRegistry.ts",
      "line": 67,
      "exported": true
    },
    {
      "name": "AgentRunRequest",
      "kind": "type",
      "file": "src/services/passthrough/protocol.ts",
      "line": 87,
      "exported": true
    },
    {
      "name": "AgentScaffoldFrontmatter",
      "kind": "interface",
      "file": "src/types/scaffoldFrontmatter.ts",
      "line": 51,
      "exported": true
    },
    {
      "name": "AgentsDetector",
      "kind": "class",
      "file": "src/services/import/agentsDetector.ts",
      "line": 7,
      "exported": true
    },
    {
      "name": "AgentSequenceStep",
      "kind": "interface",
      "file": "src/workflow/types.ts",
      "line": 320,
      "exported": true
    },
    {
      "name": "AgentStartEvent",
      "kind": "interface",
      "file": "src/services/ai/agentEvents.ts",
      "line": 7,
      "exported": true
    },
    {
      "name": "AgentStatus",
      "kind": "interface",
      "file": "src/workflow/types.ts",
      "line": 114,
      "exported": true
    },
    {
      "name": "AgentStepEvent",
      "kind": "interface",
      "file": "src/services/ai/agentEvents.ts",
      "line": 12,
      "exported": true
    },
    {
      "name": "AgentTemplateContext",
      "kind": "interface",
      "file": "src/generators/agents/templates/types.ts",
      "line": 16,
      "exported": true
    },
    {
      "name": "AgentType",
      "kind": "type",
      "file": "src/workflow/orchestration/agentOrchestrator.ts",
      "line": 31,
      "exported": true
    },
    {
      "name": "AgentType",
      "kind": "type",
      "file": "src/services/ai/agentEvents.ts",
      "line": 5,
      "exported": true
    },
    {
      "name": "AgentType",
      "kind": "type",
      "file": "src/generators/agents/agentTypes.ts",
      "line": 18,
      "exported": true
    },
    {
      "name": "AgentUpdate",
      "kind": "interface",
      "file": "src/workflow/types.ts",
      "line": 281,
      "exported": true
    },
    {
      "name": "AIDependencies",
      "kind": "interface",
      "file": "src/services/shared/types.ts",
      "line": 23,
      "exported": true
    }
  ],
  "dependencies": {
    "mostImported": [
      {
        "file": "src/types.ts",
        "importedBy": 26,
        "description": "Type definitions"
      },
      {
        "file": "src/utils/i18n.ts",
        "importedBy": 25,
        "description": "Shared utilities and helpers"
      },
      {
        "file": "src/workflow/types.ts",
        "importedBy": 21,
        "description": "Type definitions"
      },
      {
        "file": "src/utils/cliUI.ts",
        "importedBy": 20,
        "description": "Shared utilities and helpers"
      },
      {
        "file": "src/services/mcp/gateway/response.ts",
        "importedBy": 20
      },
      {
        "file": "src/generators/shared/structures/types.ts",
        "importedBy": 19,
        "description": "Type definitions"
      },
      {
        "file": "src/services/ai/schemas.ts",
        "importedBy": 16,
        "description": "AI/LLM integration"
      },
      {
        "file": "src/utils/theme.ts",
        "importedBy": 15,
        "description": "Shared utilities and helpers"
      },
      {
        "file": "src/workflow/index.ts",
        "importedBy": 13,
        "description": "workflow module exports"
      },
      {
        "file": "src/services/ai/agentEvents.ts",
        "importedBy": 12,
        "description": "AI/LLM integration"
      },
      {
        "file": "src/services/semantic/index.ts",
        "importedBy": 12,
        "description": "semantic module exports"
      },
      {
        "file": "src/services/semantic/types.ts",
        "importedBy": 11,
        "description": "Type definitions"
      },
      {
        "file": "src/generators/agents/agentTypes.ts",
        "importedBy": 10,
        "description": "AI agent definitions"
      },
      {
        "file": "src/services/ai/tools/index.ts",
        "importedBy": 9,
        "description": "Module exports"
      },
      {
        "file": "src/services/shared/index.ts",
        "importedBy": 9,
        "description": "shared module exports"
      },
      {
        "file": "src/services/import/types.ts",
        "importedBy": 9,
        "description": "Type definitions"
      },
      {
        "file": "src/services/ai/providerFactory.ts",
        "importedBy": 8,
        "description": "AI/LLM integration"
      },
      {
        "file": "src/utils/fileMapper.ts",
        "importedBy": 7,
        "description": "Shared utilities and helpers"
      },
      {
        "file": "src/workflow/skills/index.ts",
        "importedBy": 7,
        "description": "skills module exports"
      },
      {
        "file": "src/services/workflow/index.ts",
        "importedBy": 7,
        "description": "workflow module exports"
      }
    ]
  },
  "stats": {
    "totalSymbols": 773,
    "exportedSymbols": 650,
    "analysisTimeMs": 1165
  },
  "keyFiles": [
    {
      "path": "src/index.ts",
      "description": "Main library entry point",
      "category": "entrypoint"
    },
    {
      "path": "src/workflow/agents/index.ts",
      "description": "agents module exports",
      "category": "entrypoint"
    },
    {
      "path": "src/workflow/gates/index.ts",
      "description": "Module exports",
      "category": "entrypoint"
    },
    {
      "path": "src/workflow/index.ts",
      "description": "workflow module exports",
      "category": "entrypoint"
    },
    {
      "path": "src/workflow/orchestration/index.ts",
      "description": "Module exports",
      "category": "entrypoint"
    },
    {
      "path": "src/workflow/plans/index.ts",
      "description": "plans module exports",
      "category": "entrypoint"
    },
    {
      "path": "src/workflow/skills/index.ts",
      "description": "skills module exports",
      "category": "entrypoint"
    },
    {
      "path": "jest.config.js",
      "description": "Tool configuration",
      "category": "config"
    },
    {
      "path": "package.json",
      "description": "Package manifest",
      "category": "config"
    },
    {
      "path": "tsconfig.json",
      "description": "TypeScript configuration",
      "category": "config"
    },
    {
      "path": "src/generators/agents/templates/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/generators/documentation/templates/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/generators/plans/templates/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/generators/shared/structures/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/services/import/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/services/mcp/gateway/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/services/reverseSync/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/services/semantic/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/services/shared/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/services/sync/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/utils/prompts/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/workflow/plans/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/workflow/skills/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/workflow/types.ts",
      "description": "Type definitions",
      "category": "types"
    },
    {
      "path": "src/services/ai/agents/index.ts",
      "description": "agents module exports",
      "category": "service"
    },
    {
      "path": "src/services/ai/index.ts",
      "description": "ai module exports",
      "category": "service"
    },
    {
      "path": "src/services/ai/prompts/index.ts",
      "description": "prompts module exports",
      "category": "service"
    },
    {
      "path": "src/services/ai/tools/index.ts",
      "description": "Module exports",
      "category": "service"
    },
    {
      "path": "src/services/autoFill/autoFillService.ts",
      "description": "Service class",
      "category": "service"
    }
  ],
  "navigation": {
    "tests": "**/__tests__/**/*.ts",
    "config": [
      "package.json",
      "tsconfig.json",
      "jest.config.js"
    ],
    "types": [
      "src/types.ts",
      "src/workflow/types.ts",
      "src/workflow/skills/types.ts",
      "src/workflow/plans/types.ts",
      "src/utils/prompts/types.ts",
      "src/services/sync/types.ts",
      "src/services/shared/types.ts",
      "src/services/semantic/types.ts",
      "src/services/reverseSync/types.ts",
      "src/services/import/types.ts"
    ],
    "mainLogic": [
      "src/services"
    ]
  }
}

================================================
FILE: .context/docs/development-workflow.md
================================================
---
type: doc
name: development-workflow
description: Day-to-day engineering processes, branching, and contribution guidelines
category: workflow
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Development Workflow

This document covers the day-to-day engineering processes for contributing to `@dotcontext/cli`, including branching conventions, local development setup, release procedures, and code review expectations.

## Branching & Releases

### Branch naming

All work branches fork from `main`. Use descriptive prefixes:

| Prefix        | Purpose                          | Example                              |
| ------------- | -------------------------------- | ------------------------------------ |
| `feature/`    | New functionality                | `feature/mcp-tool-support`           |
| `fix/`        | Bug fixes                        | `fix/auto-fill`                      |
| `chore/`      | Maintenance, docs, refactoring   | `chore/improve-documentation-for-usage` |
| `release/`    | Release preparation              | `release/0.7.1`                      |

### Merge strategy

- Feature and fix branches merge into `main` via pull request.
- Release branches are created from `main`, finalized with a version bump, then merged back.
- Squash merges are preferred for feature branches to keep history clean.

### Versioning

The project follows [semantic versioning](https://semver.org/):

- **Patch** (0.7.x): bug fixes, documentation updates, non-breaking tweaks.
- **Minor** (0.x.0): new features, new CLI commands, non-breaking additions.
- **Major** (x.0.0): breaking changes to CLI interface, configuration format, or public APIs.

### Release scripts

```bash
npm run release          # Bump patch, build, publish to npm
npm run release:minor    # Bump minor, build, publish to npm
npm run release:major    # Bump major, build, publish to npm
```

Each release script runs `npm version <level>` (which triggers the `version` script to rebuild) followed by `npm publish --access public`. The `prepublishOnly` hook ensures a fresh build before every publish.

### Changelog

Update `CHANGELOG.md` before each release with a summary of changes, referencing relevant pull requests.

## Local Development

### Prerequisites

- Node.js >= 20.0.0
- npm (ships with Node)
- Git

### Setup

```bash
git clone https://github.com/vinilana/ai-coders-context.git
cd ai-coders-context
npm install
```

### Common commands

| Command           | Description                                      |
| ----------------- | ------------------------------------------------ |
| `npm run dev`     | Run CLI from source using tsx (fast, no build step) |
| `npm run build`   | Compile TypeScript to `dist/` via tsc             |
| `npm start`       | Run the compiled CLI from `dist/index.js`         |
| `npm test`        | Run the full Jest test suite                      |

### Development loop

1. Create a branch from `main` following the naming conventions above.
2. Make changes in `src/`.
3. Test interactively with `npm run dev -- <command>` (e.g., `npm run dev -- workflow --help`).
4. Run `npm test` to verify nothing is broken.
5. Run `npm run build` to confirm the TypeScript compiles cleanly.
6. Commit, push, and open a pull request against `main`.

### Environment variables

The CLI supports locale overrides via `DOTCONTEXT_LANG` (`en` or `pt-BR`).

For AI-generated filling or refresh, install MCP with `npx -y @dotcontext/cli@latest mcp:install` and use your connected AI tool instead of standalone CLI commands.

Use a `.env` file in the project root (loaded via dotenv). Do not commit `.env` files.

## Code Review Expectations

### What reviewers look for

- **Correctness**: Does the change do what it claims? Are edge cases handled?
- **Type safety**: TypeScript strict mode is enabled. No `any` casts without justification.
- **Test coverage**: New features should include tests. Bug fixes should include a regression test when feasible.
- **CLI UX**: Interactive prompts (inquirer), spinners (ora), and colored output (chalk) should be consistent with existing patterns.
- **i18n**: User-facing strings should go through the i18n utility (`src/utils/i18n.ts`) for both English and Portuguese (pt-BR).
- **No secrets**: Ensure API keys, tokens, and credentials are never committed.

### Pull request checklist

- [ ] Branch is up to date with `main`
- [ ] `npm test` passes locally
- [ ] `npm run build` succeeds without errors
- [ ] New/changed user-facing strings are internationalized
- [ ] CHANGELOG entry drafted (for non-trivial changes)
- [ ] PR description explains the "why" behind the change


================================================
FILE: .context/docs/harness-roadmap.md
================================================
---
type: doc
name: harness-roadmap
description: Product roadmap for evolving dotcontext into a harness engineering platform
category: roadmap
generated: 2026-04-11
status: filled
scaffoldVersion: "2.0.0"
---

# Harness Roadmap

This roadmap describes how dotcontext can evolve from its current architecture split into a full harness engineering platform.

The intended product shape is:

- `dotcontext/cli` as the operator-facing interface
- `dotcontext/harness` as the reusable runtime and domain layer
- `dotcontext/mcp` as the Model Context Protocol adapter over the harness

The roadmap is organized by product capability, not by code folder, because harness engineering is ultimately about runtime control, feedback, and reliability.

## Roadmap Principles

The roadmap assumes these design principles:

- transport adapters should stay thinner than the harness runtime
- runtime state should be explicit, inspectable, and durable
- computational sensors should be preferred where possible
- inferential controls should be added where deterministic checks are insufficient
- every autonomous capability should have matching observability and back-pressure
- PREVC should be treated as a strong default workflow, but not the only future execution model

## Now

These are the next capabilities that should be built on top of the current architecture. They have the best ratio of product value to implementation risk.

### 1. Session Runtime

Goal: make long-running harness execution first-class.

Features:

- persistent session objects for agent runs
- resumable execution with checkpoints
- append-only event log per session
- explicit run metadata: task, owner, repo, agents involved, timestamps
- artifact store for outputs, handoffs, and evidence

Why now:

- the architecture is already split into `cli`, `harness`, and `mcp`
- session state is the foundation for evals, replay, approvals, and observability

### 2. Sensors and Back-Pressure

Goal: formalize the harness feedback layer.

Features:

- sensors as first-class runtime concepts
- built-in computational sensors:
  - build
  - typecheck
  - lint
  - test
  - structural constraints
- sensor result model with pass/fail, severity, evidence, and timestamps
- configurable back-pressure so critical sensor failures block completion
- task completion rules based on sensor status instead of prompt-only conventions

Why now:

- this is where harness engineering starts to become materially different from prompt engineering
- it directly improves trust in agent output

### 3. Execution Traces and Observability

Goal: make agent behavior inspectable.

Features:

- trace timeline for tool calls, state transitions, retries, and failures
- normalized event model inside `dotcontext/harness`
- logs linked to session and task IDs
- evidence records attached to plans, phases, and approvals
- reporting views for failed runs and repeated failure classes

Why now:

- once sessions and sensors exist, traces become the main debugging surface
- this also creates the basis for future evaluation datasets

### 4. Task Contracts

Goal: replace vague agent assignments with explicit runtime contracts.

Features:

- structured task definition:
  - goal
  - inputs
  - expected outputs
  - acceptance criteria
  - required sensors
  - assigned agent type
- handoff contracts between planner, executor, reviewer, and evaluator
- artifact schema for task outputs

Why now:

- this reduces ambiguity in both single-agent and multi-agent operation
- it is the cleanest way to connect plans, workflow, sensors, and evidence

## Next

These should follow once sessions, sensors, traces, and task contracts exist.

### 5. Evaluator Layer

Goal: separate execution from judgment.

Features:

- evaluator agent role as a first-class harness component
- scorecards for:
  - correctness
  - architecture fit
  - test adequacy
  - docs adequacy
  - policy compliance
- evaluator loops for long-running tasks
- configurable stopping conditions based on evaluation quality

Why next:

- evaluator quality depends on session evidence and sensor results already existing

### 6. Guides as Runtime Assets

Goal: move guides from passive docs into active harness inputs.

Features:

- versioned guide assets
- guide bundles by task type, stack, or repo topology
- guide selection logic based on task contract and repo context
- constraints tied to guides, not just narrative instructions
- progressive disclosure of guides rather than monolithic injection

Why next:

- the repo already has docs, skills, and playbooks
- the next step is turning them into selected runtime assets with explicit effect

### 7. Harness Templates

Goal: package battle-tested harness configurations for common project types.

Features:

- templates for:
  - TypeScript monorepo
  - CRUD backend
  - frontend app
  - CLI tool
  - event-driven worker
- each template bundles:
  - default guides
  - default sensors
  - recommended agent topology
  - workflow defaults
  - expected artifacts

Why next:

- templates are the most scalable way to make harness engineering reusable

### 8. Multi-Agent Topologies

Goal: support controlled multi-agent execution as a native harness feature.

Features:

- planner / executor / reviewer / evaluator topology
- agent-specific task contracts
- isolated context windows by role
- artifact-based handoffs
- retry and escalation rules per role

Why next:

- the current codebase already models agents and orchestration
- after contracts and evidence exist, multi-agent operation becomes much safer to implement

## Later

These are strategically important, but should come after the runtime core is stable.

### 9. Policy and Governance Engine

Goal: make operational rules enforceable at runtime.

Features:

- policy rules for tools, paths, and environments
- approval requirements based on risk or scope
- secret handling and restricted connector policies
- role-based execution permissions
- audit-grade event trail

### 10. Replay and Evaluation Dataset Generation

Goal: turn harness usage into reusable learning data.

Features:

- replay of full sessions
- diff between expected and observed execution paths
- failure clustering
- datasets for prompt, workflow, and policy improvement
- model comparison using the same harness trace corpus

### 11. Workflow Engine Expansion

Goal: make PREVC one execution strategy among several.

Features:

- PREVC as default workflow template
- support for alternate engines:
  - fast single-pass execution
  - gated enterprise workflow
  - long-running autonomous workflow
  - review-heavy workflow
- workflow selection by task type and risk profile

### 12. Package Publication and Platform Distribution

Goal: turn the internal split into a public package and release model.

Features:

- independent package publication for:
  - `@dotcontext/cli`
  - `@dotcontext/harness`
  - `@dotcontext/mcp`
- package-specific smoke tests
- release channels and compatibility guarantees
- future adapters beyond MCP, such as HTTP or embedded SDK execution

## Suggested Sequencing

If the team wants a strict order, this is the most coherent path:

1. sessions
2. sensors
3. traces
4. task contracts
5. evaluator layer
6. guide assets
7. harness templates
8. multi-agent topologies
9. policy engine
10. replay and dataset generation
11. workflow engine expansion
12. independent package publication

## Success Criteria By Stage

### Stage 1 Success

The product can run a task with:

- durable session state
- explicit task contract
- sensor-backed completion rules
- inspectable trace output

### Stage 2 Success

The product can run the same task with:

- selected guides
- evaluator feedback
- template-driven defaults
- multi-agent handoffs with evidence

### Stage 3 Success

The product can operate in production with:

- policy enforcement
- replayability
- measurable harness quality
- package-level distribution and upgrade workflows

## Practical Recommendation

If only one quarter of work can be funded, the best roadmap slice is:

1. sessions
2. sensors with back-pressure
3. traces
4. task contracts

That is the smallest set that makes dotcontext meaningfully recognizable as a harness engineering platform instead of only an MCP-enabled workflow tool.


================================================
FILE: .context/docs/harness-split-foundation.md
================================================
---
type: doc
name: harness-split-foundation
description: Detailed explanation of the first internal split between the CLI boundary and the harness runtime
category: architecture
generated: 2026-04-10
status: filled
scaffoldVersion: "2.0.0"
---

# Harness Split Foundation

This document explains the first structural changes made on branch `feat/harness-split-foundation`, why they matter, and how they move dotcontext toward a real harness engineering product model.

The short version is:

- the codebase now has an explicit `cli` boundary and an explicit `harness` boundary,
- the codebase now also has an explicit `mcp` boundary, so transport is modeled separately from domain,
- CLI-only concerns were moved away from the MCP runtime surface,
- core logic for `agent`, `plan`, `context`, and `skill` is now being extracted into harness services,
- the repository can now generate package bundles for `cli`, `harness`, and `mcp` in `.release/packages`,
- compatibility shims were kept in place so the refactor does not force a big-bang migration,
- and the package now exposes subpath entrypoints that prepare the future split between `dotcontext/cli`, `dotcontext/harness`, and a dedicated MCP adapter surface.

This is a foundation release, not the final split.

## Why This Change Was Needed

Before this refactor, the repository already contained two distinct product shapes:

1. An operator-facing CLI centered on [src/index.ts](/home/aicoders/workspace/ai-coders-context/src/index.ts)
2. A reusable runtime centered on [src/services/mcp/mcpServer.ts](/home/aicoders/workspace/ai-coders-context/src/services/mcp/mcpServer.ts), [src/services/workflow/workflowService.ts](/home/aicoders/workspace/ai-coders-context/src/services/workflow/workflowService.ts), and [src/workflow](/home/aicoders/workspace/ai-coders-context/src/workflow)

Those concerns were still mixed in the import graph and in the mental model of the codebase. In practice, that made the MCP runtime look like a feature of the CLI package instead of a reusable harness layer.

The goal of this iteration was not to rename packages yet. The goal was to make the internal architecture match the intended product direction first.

## What Changed

## 1. New Explicit Entry Boundaries

Three explicit entry modules now exist:

- [src/cli/index.ts](/home/aicoders/workspace/ai-coders-context/src/cli/index.ts)
- [src/harness/index.ts](/home/aicoders/workspace/ai-coders-context/src/harness/index.ts)
- [src/mcp/index.ts](/home/aicoders/workspace/ai-coders-context/src/mcp/index.ts)

These modules create a clear distinction between:

- `cli`: operator-facing commands, local workflows, installation, sync, reporting
- `harness`: reusable runtime primitives and domain services
- `mcp`: Model Context Protocol adapter surface over the harness

This matters because it creates a stable import boundary inside the monolith before turning it into separate packages.

### Current intent of each boundary

| Boundary | Purpose | Examples |
| --- | --- | --- |
| `src/cli` | Thin operator surface | `MCPInstallService`, `StateDetector`, sync/import/export/report flows |
| `src/harness` | Reusable runtime surface | workflow service, harness services, orchestration types |
| `src/mcp` | Protocol adapter surface | `AIContextMCPServer`, `startMCPServer`, gateway handlers |

## 2. `src/index.ts` Now Depends on the Boundaries

The main CLI entrypoint in [src/index.ts](/home/aicoders/workspace/ai-coders-context/src/index.ts) was updated so it no longer reaches directly into as many deep service paths.

Instead, it now imports from:

- [src/cli/index.ts](/home/aicoders/workspace/ai-coders-context/src/cli/index.ts)
- [src/harness/index.ts](/home/aicoders/workspace/ai-coders-context/src/harness/index.ts)
- [src/mcp/index.ts](/home/aicoders/workspace/ai-coders-context/src/mcp/index.ts)

That is a small-looking change with large architectural impact:

- it makes the command layer consume a defined surface instead of internal details,
- it gives future package extraction a natural seam,
- and it reduces the chance that CLI code will keep accumulating harness-domain logic by accident.

## 3. `MCPInstallService` Was Reclassified as CLI Concern

The implementation of `MCPInstallService` was moved semantically to:

- [src/services/cli/mcpInstallService.ts](/home/aicoders/workspace/ai-coders-context/src/services/cli/mcpInstallService.ts)

The old file remains as a compatibility shim:

- [src/services/mcp/mcpInstallService.ts](/home/aicoders/workspace/ai-coders-context/src/services/mcp/mcpInstallService.ts)

### Why this matters

`MCPInstallService` configures editor and tool clients so they can point to the MCP server. That is an operator/install concern, not part of the harness runtime itself.

Leaving it under `services/mcp` suggested the wrong ownership model:

- as if client installation were part of the runtime,
- as if the harness were defined by transport bootstrapping,
- and as if MCP transport and local UX were the same subsystem.

By moving it under `services/cli`, the code now reflects the intended product model:

- `dotcontext/cli` installs and operates
- `dotcontext/harness` runs the harness

## 4. `StateDetector` Was Reclassified as CLI Concern

The implementation of `StateDetector` was moved semantically to:

- [src/services/cli/stateDetector.ts](/home/aicoders/workspace/ai-coders-context/src/services/cli/stateDetector.ts)

The old file remains as a compatibility shim:

- [src/services/state/stateDetector.ts](/home/aicoders/workspace/ai-coders-context/src/services/state/stateDetector.ts)

### Why this matters

`StateDetector` is used to drive local UX and operator workflows:

- detect whether `.context` exists,
- detect whether scaffolding is unfilled,
- detect whether docs are outdated for local prompts and menus.

That is useful, but it is not core harness runtime logic. It is a local operational sensor used by the CLI layer.

Moving it clarifies that not every useful sensor belongs inside the reusable harness core. Some sensors exist only to support local operator experience.

## 5. `services/mcp` Was Tightened Around Adapter Concerns

The file [src/services/mcp/index.ts](/home/aicoders/workspace/ai-coders-context/src/services/mcp/index.ts) was updated to focus on MCP transport adapter exports only.

It no longer re-exports `MCPInstallService`.

The file [src/services/mcp/README.md](/home/aicoders/workspace/ai-coders-context/src/services/mcp/README.md) was also updated to say explicitly that this directory is about the MCP adapter surface, not CLI install/setup concerns and not the center of the domain model.

This is important because the codebase needs a clean answer to the question:

"What is the harness runtime?"  
and separately:  
"What helps a user operate that runtime locally?"  
and also:  
"What protocol exposes that runtime to external agents?"

## 6. Package Subpath Exports Were Added

[package.json](/home/aicoders/workspace/ai-coders-context/package.json) now exposes:

- `"./cli": "./dist/cli/index.js"`
- `"./harness": "./dist/harness/index.js"`
- `"./mcp": "./dist/mcp/index.js"`

The package is still `@dotcontext/cli`, but it now has internal subpath exports that model the future product split and the adapter/runtime separation.

This gives us three benefits:

1. It creates a package-level contract before the package split happens.
2. It lets internal and future external consumers target the right surface intentionally.
3. It reduces migration risk because the conceptual split can stabilize before publish-time restructuring.

## 7. Harness Services Were Introduced

The first transport-agnostic harness services now exist under:

- [src/services/harness/agentsService.ts](/home/aicoders/workspace/ai-coders-context/src/services/harness/agentsService.ts)
- [src/services/harness/plansService.ts](/home/aicoders/workspace/ai-coders-context/src/services/harness/plansService.ts)
- [src/services/harness/contextService.ts](/home/aicoders/workspace/ai-coders-context/src/services/harness/contextService.ts)
- [src/services/harness/skillsService.ts](/home/aicoders/workspace/ai-coders-context/src/services/harness/skillsService.ts)

These services now hold the application logic that was previously embedded directly in MCP gateway handlers.

This means the MCP gateway is starting to behave like a real adapter:

- request comes in,
- gateway translates params,
- harness service executes domain logic,
- gateway formats the response.

That is a major step toward a true harness architecture.

## 8. Shared Execution Helpers Were Neutralized

Non-interactive helpers such as:

- `minimalUI`
- `mockTranslate`
- neutral tool execution context

were moved into [src/services/shared/executionContext.ts](/home/aicoders/workspace/ai-coders-context/src/services/shared/executionContext.ts).

This matters because harness services should not depend on files living under `mcp/gateway`. The domain layer must not import utilities from the adapter layer.

## 9. Boundary Tests Were Added

Two small tests were added:

- [src/cli/index.test.ts](/home/aicoders/workspace/ai-coders-context/src/cli/index.test.ts)
- [src/harness/index.test.ts](/home/aicoders/workspace/ai-coders-context/src/harness/index.test.ts)
- [src/mcp/index.test.ts](/home/aicoders/workspace/ai-coders-context/src/mcp/index.test.ts)

These are not deep behavior tests. They are contract tests for the new public surfaces.

That matters because once a boundary is introduced, it becomes part of the architecture. The tests make sure the intended surfaces stay visible and do not silently collapse back into ad hoc imports.

## 10. Package Bundle Preparation Was Added

The repository can now generate package-shaped bundle directories with:

```bash
npm run build:packages
```

This produces:

- `.release/packages/cli`
- `.release/packages/harness`
- `.release/packages/mcp`

Each bundle now includes the generated `dist/` tree, package metadata, `LICENSE`, package-specific `README.md`, and the CLI bundle also includes `prompts/`.

The MCP adapter also has a dedicated executable entrypoint in [src/mcp/bin.ts](/home/aicoders/workspace/ai-coders-context/src/mcp/bin.ts), which prepares the future `@dotcontext/mcp` package to ship as a real runnable adapter instead of only as a library surface.

This is still a preparation step, not the final multi-package publication workflow, but it closes the gap between architecture and package artifacts.

## 11. Planning and Agent Artifacts Were Added

The transformation is also documented in `.context`:

- [dotcontext-harness-engineering-transformation.md](/home/aicoders/workspace/ai-coders-context/.context/plans/dotcontext-harness-engineering-transformation.md)
- [agents README](/home/aicoders/workspace/ai-coders-context/.context/agents/README.md)

And the following specialized playbooks were added:

- [agent-systems-designer.md](/home/aicoders/workspace/ai-coders-context/.context/agents/agent-systems-designer.md)
- [cli-experience-architect.md](/home/aicoders/workspace/ai-coders-context/.context/agents/cli-experience-architect.md)
- [harness-platform-architect.md](/home/aicoders/workspace/ai-coders-context/.context/agents/harness-platform-architect.md)
- [workflow-orchestration-engineer.md](/home/aicoders/workspace/ai-coders-context/.context/agents/workflow-orchestration-engineer.md)
- [harness-quality-auditor.md](/home/aicoders/workspace/ai-coders-context/.context/agents/harness-quality-auditor.md)
- [migration-release-manager.md](/home/aicoders/workspace/ai-coders-context/.context/agents/migration-release-manager.md)

These are not runtime changes, but they are still part of harness engineering: they formalize the control-plane thinking and make the transformation process itself more machine-readable and repeatable.

## Backward Compatibility Strategy

This iteration intentionally avoided a breaking rewrite.

The old import paths still exist as shims:

- [src/services/mcp/mcpInstallService.ts](/home/aicoders/workspace/ai-coders-context/src/services/mcp/mcpInstallService.ts)
- [src/services/state/stateDetector.ts](/home/aicoders/workspace/ai-coders-context/src/services/state/stateDetector.ts)

That means the code can evolve in stages:

1. Move ownership semantically
2. Preserve old paths temporarily
3. Migrate callers incrementally
4. Remove the shims only when the new boundaries are stable

This is deliberate. A package split done without this intermediate stage would create unnecessary churn and increase regression risk.

## How This Aligns With Harness Engineering

This refactor is aligned with harness engineering in several ways.

## 1. It Separates the Operator Layer From the Runtime Layer

Harness engineering is not just "having an MCP server." It is the discipline of shaping the environment around agents so that runtime behavior, constraints, tooling, and feedback loops are explicit and governable.

The new split reflects that:

- `cli` is the operator-facing outer shell
- `harness` is the reusable runtime substrate
- `mcp` is the transport adapter over that substrate

That is much closer to the real harness mental model than a single mixed command package.

## 2. It Makes the Outer Harness More Explicit

The explicit `cli` boundary represents the local operator harness:

- install flows,
- diagnostics,
- local status detection,
- sync/import/export assistance.

The explicit `harness` boundary represents the reusable runtime harness:

- context scaffolding,
- workflow management,
- orchestration,
- harness services.

The explicit `mcp` boundary represents the transport adapter:

- MCP server lifecycle,
- gateway registration,
- request/response translation.

Harness engineering improves when those two layers are visible and reasoned about separately.

## 3. It Reduces Coupling Between Transport and Domain Logic

One of the goals in the broader plan is to make MCP an adapter, not the product itself.

This change now goes further than the first foundation pass:

- the runtime now has a named harness-facing entrypoint,
- the transport now has a separate MCP-facing entrypoint,
- CLI-side install/setup no longer masquerades as MCP runtime logic,
- and core `agent`, `plan`, `context`, and `skill` logic has started moving into transport-agnostic harness services.

The split is also no longer only conceptual, because the repository can emit package-shaped artifacts for all three boundaries.

That is consistent with harness engineering because a good harness must survive changes in transport, toolchain, and model behavior.

## 4. It Treats Compatibility as a Runtime Constraint, Not an Afterthought

Harness engineering values reliable systems over clever rewrites. The shim approach reflects that mindset.

Instead of forcing immediate breakage:

- old paths still resolve,
- behavior remains stable,
- the architecture can improve incrementally under test,
- and package-shaped outputs can be exercised before changing publication strategy.

This is the same design instinct used in good harnesses generally: constrain change, preserve observability, and avoid destabilizing the system while it is being improved.

## 5. It Improves Agent Readability of the Codebase

For human developers and coding agents alike, explicit boundaries reduce ambiguity.

Before:

- an agent reading `services/mcp` could reasonably infer that install/configuration and runtime were one concern.

After:

- the code states more clearly what belongs to operator UX,
- what belongs to harness runtime,
- and which files are temporary compatibility glue.

That is directly relevant to harness engineering because the harness itself must be legible to the agents that work within it.

## 6. It Supports “Build to Delete” Rather Than Big-Bang Architecture

This version does not pretend to know the final package shape in full detail. Instead, it introduces seams:

- subpath exports,
- explicit boundaries,
- compatibility shims,
- boundary tests,
- and local package bundle generation.

That is a strong harness-engineering move because it keeps the system adaptable as model behavior, transport assumptions, and product priorities evolve.

## What This Version Does Not Do Yet

This foundation is intentionally incomplete. It does not yet:

- extract every remaining gateway into harness services,
- create a fully transport-agnostic harness core beneath every adapter path,
- rename or publish a separate `dotcontext/harness` package,
- rename or publish a separate `dotcontext/mcp` package,
- automate real versioning and publish workflows for the generated package bundles,
- introduce first-class guides, sensors, evaluations, traces, or replay artifacts as runtime concepts,
- or redefine PREVC as one harness strategy among several.

Those remain part of the next phases described in the transformation plan.

## Validation

The code changes associated with this foundation were validated with:

```bash
npm run build
npm test -- --runInBand
npm run build:packages
```

At the time of this stage completion, the full suite passed with 21 test suites and 210 tests, and the package bundle pipeline generated all three bundles successfully.

## Recommended Next Steps

The next technically coherent steps are:

1. Decide which current workflow concepts are permanent harness primitives and which are PREVC-specific policy.
2. Introduce a clearer internal module map for sessions, guides, sensors, plans, agents, and evaluations.
3. Design the real publish/version workflow for `@dotcontext/cli`, `@dotcontext/harness`, and `@dotcontext/mcp`.
4. Keep shrinking the CLI so it orchestrates the harness instead of owning more domain behavior.
5. Remove compatibility shims only after the new import surfaces are stable and internal callers are migrated.

## Summary

This version did not change the external story dramatically yet. What it changed was the architecture’s truthfulness.

The codebase now says, more clearly than before:

- there is a CLI boundary,
- there is a harness boundary,
- there is an MCP adapter boundary,
- installation is not the runtime,
- local status sensing is not the same thing as reusable harness logic,
- adapter helpers do not belong inside the domain layer,
- and the future package split can happen on top of explicit seams instead of ad hoc imports.

That is exactly the right kind of first move for a harness engineering transformation.


================================================
FILE: .context/docs/project-overview.md
================================================
---
type: doc
name: project-overview
description: High-level overview of the project, its purpose, and key components
category: overview
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Project Overview

**@dotcontext/cli** (v0.8.0) is an MCP-first context engineering toolkit for codebase documentation and AI agent prompts. MCP-enabled AI tools create and refresh the `.context` directory structure containing docs, agents, plans, and skills, while the standalone CLI now focuses on workflow management, sync/import utilities, reporting, and MCP configuration. The project also supports semantic code analysis via tree-sitter, a PREVC workflow engine, MCP server mode for AI tool integration, and context export/sync to Claude, Gemini, and Codex.

## Codebase Reference

The machine-readable codebase map lives at `.context/docs/codebase-map.json`. It contains file listings, dependency graphs, and structural metadata used by MCP tools, workflow orchestration, and codebase analysis features.

## Quick Facts

| Property         | Value                                      |
| ---------------- | ------------------------------------------ |
| Package name     | `@dotcontext/cli`                       |
| Version          | 0.8.0                                      |
| License          | MIT                                        |
| Node requirement | >= 20.0.0                                  |
| Language          | TypeScript (target ES2020, CommonJS)       |
| Binary           | `dotcontext`                               |
| Repository       | https://github.com/vinilana/ai-coders-context |

## Entry Points

- **CLI binary**: `dist/index.js` (mapped to the `dotcontext` command via `package.json` `bin` field)
- **Source entry**: `src/index.ts` -- registers all commander commands and starts the CLI
- **MCP server**: accessible through the `mcp` CLI command for AI tool integration

## Key Exports

The package ships only compiled output from `dist/`. Refer to `.context/docs/codebase-map.json` for a full inventory of exported modules and their relationships.

Primary public surface:
- CLI commands exposed through commander (sync, import/export, workflow, reporting, MCP setup, etc.)
- MCP server tools (via `src/services/mcp/`)

## File Structure

```
src/
  index.ts              # CLI entry point (commander setup)
  cli.test.ts           # CLI integration test
  types.ts              # Shared type definitions
  version.ts            # Version constant
  generators/           # Template generators
    agents/             # Agent prompt templates
    documentation/      # Doc templates
    plans/              # Plan templates
    shared/             # Shared generator utilities
    skills/             # Skill templates
  services/             # Core business logic
    ai/                 # MCP-facing AI tool definitions and provider helpers
    autoFill/           # Static scaffold auto-fill from semantic analysis
    export/             # Context export to AI tools
    import/             # Context import
    init/               # .context scaffolding initializer used by MCP tools
    mcp/                # MCP server and gateway handlers
    qa/                 # QA scaffolding service
    report/             # Context and workflow reporting
    reverseSync/        # Import external changes back into .context
    semantic/           # Tree-sitter semantic analysis
    shared/             # Shared helpers and service types
    stack/              # Stack detection and scaffold filtering
    state/              # Interactive state detection
    sync/               # Context sync to AI tools (Claude, Gemini, Codex)
    workflow/           # PREVC workflow service layer
    ... (and more)
  utils/                # Shared utilities
    frontMatter.*       # YAML frontmatter parsing
    i18n.*              # Internationalization (en, pt-BR)
    prompts/            # CLI prompt definitions (inquirer)
    ...
  workflow/             # Workflow config and state
.context/               # Generated context directory
  docs/                 # Documentation files
  agents/               # Agent playbooks
  plans/                # Plan documents
  skills/               # Skill definitions
```

## Technology Stack Summary

| Layer          | Technology                                           |
| -------------- | ---------------------------------------------------- |
| Runtime        | Node.js >= 20                                        |
| Language       | TypeScript 5.x (strict mode, CommonJS output)        |
| CLI framework  | commander 14.x                                       |
| Interactive UI | inquirer 12.x, chalk 4.x, ora 5.x, boxen, figures   |
| AI SDKs        | @ai-sdk/anthropic, @ai-sdk/openai, @ai-sdk/google, ai (Vercel AI SDK) |
| MCP            | @modelcontextprotocol/sdk 1.x                        |
| Code analysis  | tree-sitter, tree-sitter-typescript (optional)        |
| Validation     | zod 4.x                                              |
| Testing        | Jest 30.x with ts-jest                               |
| Dev tooling    | tsx (development runner), tsc (build)                 |

## Getting Started Checklist

1. Clone the repository: `git clone https://github.com/vinilana/ai-coders-context.git`
2. Install dependencies: `npm install`
3. Run in development mode: `npm run dev` (uses tsx for fast TypeScript execution)
4. Build for production: `npm run build`
5. Run tests: `npm test`
6. Try the CLI: `npx -y @dotcontext/cli@latest mcp:install` to connect the package to your AI tool

## Next Steps

- Read **development-workflow.md** for branching, releases, and contribution guidelines.
- Read **testing-strategy.md** for test patterns and quality gates.
- Read **tooling.md** for scripts, IDE setup, and productivity tips.
- Explore `.context/agents/README.md` for agent playbook documentation.
- Review `.context/docs/codebase-map.json` for the full structural map of the codebase.


================================================
FILE: .context/docs/qa/README.md
================================================
# Q&A Index

Project type: **cli-tool**

Generated: 2026-03-18T21:32:55.004Z

## Getting-started

- [How do I set up and run this project?](./getting-started.md)

## Architecture

- [How is the codebase organized?](./project-structure.md)

## Operations

- [How are errors handled?](./error-handling.md)

## Testing

See [testing-strategy.md](../testing-strategy.md) in the parent docs directory for full test framework documentation.


================================================
FILE: .context/docs/qa/error-handling.md
================================================
---
slug: error-handling
category: operations
status: filled
generatedAt: 2026-03-18T21:32:54.231Z
relevantFiles:
  - src/workflow/errors.ts
  - src/services/shared/types.ts
  - src/services/mcp/gateway/response.ts
  - src/services/mcp/mcpServer.ts
---

# How are errors handled?

## Overview

Error handling in this project follows three patterns depending on the context: workflow errors (custom error classes), operation result errors (structured result objects), and MCP tool errors (structured responses returned through the MCP server).

## 1. Workflow errors (`src/workflow/errors.ts`)

The PREVC workflow engine uses a class hierarchy for typed errors:

- **`WorkflowError`** -- Base error class for all workflow-related failures.
- **`WorkflowGateError`** -- Thrown when a workflow gate blocks a phase transition. Carries the `transition` (from/to phases), the `gate` type, and a human-readable `hint` for resolution.
- **`NoPlanToApproveError`** -- Thrown when attempting to approve a plan that has not been linked.
- **`NoWorkflowError`** -- Thrown when a workflow operation is attempted but no workflow exists.

All workflow errors extend the native `Error` class and set a descriptive `name` property for easy identification in catch blocks.

## 2. Operation result errors (`src/services/shared/types.ts`)

File-based operations (import, export, sync) use an `OperationResult` pattern instead of throwing:

```typescript
interface OperationResult {
  filesCreated: number;
  filesSkipped: number;
  filesFailed: number;
  errors: OperationError[];
}

interface OperationError {
  file: string;
  error: string;
}
```

The `addError()` helper increments `filesFailed` and appends an `OperationError` entry. Multiple results can be merged with `mergeResults()`. This pattern allows batch operations to continue processing after individual file failures and report all errors at the end.

## 3. MCP tool errors (`src/services/mcp/gateway/response.ts`)

MCP gateway handlers return structured error payloads through shared response helpers:

```typescript
interface MCPToolResponse {
  content: Array<{
    type: 'text';
    text: string;
  }>;
  isError?: boolean;
}
```

The error helper serializes responses like:

```json
{
  "success": false,
  "error": "Human-readable message"
}
```

`createErrorResponse()` sets `isError: true` and wraps the JSON payload in MCP-compatible text content. At the server boundary, `src/services/mcp/mcpServer.ts` validates tool input with Zod and catches handler failures before returning them to the client.

## 4. CLI-level error handling

At the CLI level (`src/index.ts`), errors from services are caught and displayed to the user through the `CLIInterface` (`ui`) which formats output with chalk colors. Unhandled promise rejections and uncaught exceptions will cause the process to exit with a non-zero code.

## General conventions

- **Do not throw for expected batch failures** -- Use `OperationResult` to accumulate errors when processing multiple files.
- **Throw custom error classes for workflow violations** -- Callers can use `instanceof` to handle specific workflow error types.
- **Return structured error responses in MCP mode** -- Gateway handlers should use the shared response helpers instead of leaking raw exceptions to the client.
- **Include actionable hints** -- `WorkflowGateError` includes a `hint` field to guide users toward resolution.


================================================
FILE: .context/docs/qa/getting-started.md
================================================
---
slug: getting-started
category: getting-started
status: filled
generatedAt: 2026-03-18T21:32:50.399Z
---

# How do I set up and run this project?

## Prerequisites

- Node.js >= 20.0.0
- npm

## Installation (for development)

```bash
# Clone the repository
git clone https://github.com/vinilana/ai-coders-context.git
cd ai-coders-context

# Install dependencies
npm install

# Build the TypeScript source
npm run build
```

## Installation (as a user)

```bash
npm install -g @dotcontext/cli
```

After installation the `dotcontext` binary is available globally.

## Running in development

```bash
# Run directly from TypeScript source (uses tsx)
npm run dev

# Run from compiled output
npm start
```

## Key npm scripts

| Script | Purpose |
| --- | --- |
| `npm run build` | Compile TypeScript to `dist/` |
| `npm run dev` | Run from source via `tsx` |
| `npm start` | Run compiled `dist/index.js` |
| `npm test` | Run Jest test suite |
| `npm run release` | Bump patch version and publish to npm |
| `npm run release:minor` | Bump minor version and publish |
| `npm run release:major` | Bump major version and publish |

## CLI commands overview

The CLI is built with Commander. Run `dotcontext --help` to see all commands. Key commands include:

- **`dotcontext sync-agents`** -- Synchronize agent playbooks
- **`dotcontext reverse-sync`** -- Import rules, agents, and skills from AI tool directories
- **`dotcontext mcp`** -- Start in MCP (Model Context Protocol) server mode
- **`dotcontext mcp:install [tool]`** -- Install MCP configuration for AI tools
- **`dotcontext export-rules`** -- Export rules for AI coding tools
- **`dotcontext report`** -- Generate context reports
- **`dotcontext workflow init|status|advance`** -- Manage PREVC workflow phases

## Interactive mode

Running `dotcontext` with no command arguments enters interactive mode, which guides you through project state, workflow, sync, imports, and MCP setup using Inquirer prompts.

## Environment variables

- `DOTCONTEXT_LANG` -- Override the UI locale (`en` or `pt-BR`)
- A `.env` file in the project root is loaded automatically via `dotenv`

The standalone CLI no longer creates or fills context directly.
For context creation, plan scaffolding, AI-generated filling, or refresh, use MCP-enabled AI tools after running `dotcontext mcp:install`.


================================================
FILE: .context/docs/qa/project-structure.md
================================================
---
slug: project-structure
category: architecture
status: filled
generatedAt: 2026-03-18T21:32:54.231Z
relevantFiles:
  - src/index.ts
  - src/generators
  - src/services
  - src/utils
  - src/types.ts
  - src/workflow
  - src/version.ts
---

# How is the codebase organized?

## Top-level layout

```
.context/          # Generated documentation and agent config (output of the tool itself)
.github/workflows/ # CI (ci.yml) and release (release.yml) pipelines
dist/              # Compiled JavaScript output (git-ignored)
prompts/           # Prompt templates used by generators
scripts/           # Build/utility scripts
src/               # TypeScript source code (all application logic)
```

## Source directory (`src/`)

### Entry point

- **`src/index.ts`** -- CLI entry point. Registers all Commander commands, wires up services via dependency injection, handles interactive mode, and locale detection.

### Core directories

| Directory | Purpose |
| --- | --- |
| `src/generators/` | Content generation engines (agents, documentation, plans, skills) |
| `src/services/` | Business logic organized by feature domain |
| `src/utils/` | Shared utilities (CLI UI, i18n, theme, file mapping, frontmatter parsing) |
| `src/types/` | Shared TypeScript type definitions |
| `src/workflow/` | PREVC workflow engine (phases, roles, gates, orchestration, collaboration) |
| `src/prompts/` | Prompt-related modules |

### Services (`src/services/`)

Each service is a self-contained module with its own directory:

| Service | Purpose |
| --- | --- |
| `ai/` | MCP-facing AI tool definitions, schemas, and provider helpers |
| `autoFill/` | Static content filling from semantic analysis |
| `export/` | Rule export for AI coding tools (Cursor, Windsurf, etc.) |
| `import/` | Import rules and agents from external sources |
| `init/` | Project scaffolding used by MCP context tools |
| `mcp/` | MCP (Model Context Protocol) server for AI tool integration |
| `qa/` | Q&A document generation |
| `quickSync/` | Quick context synchronization |
| `report/` | Context report generation |
| `reverseSync/` | Reverse synchronization (merge external changes back) |
| `semantic/` | Semantic code analysis (optional tree-sitter) |
| `shared/` | Shared types, context root resolution, common utilities |
| `stack/` | Technology stack detection |
| `state/` | Project state detection |
| `sync/` | Agent synchronization |
| `workflow/` | Workflow service layer |

### Generators (`src/generators/`)

| Generator | Purpose |
| --- | --- |
| `agents/` | Agent playbook generation |
| `documentation/` | Documentation template generation |
| `plans/` | Implementation plan generation |
| `shared/` | Shared generator utilities |
| `skills/` | Skill document generation |

### Utilities (`src/utils/`)

| Module | Purpose |
| --- | --- |
| `cliUI.ts` | CLI output helpers (spinners, banners, tables) using chalk and ora |
| `i18n.ts` | Internationalization (English and Brazilian Portuguese) |
| `theme.ts` | Color theme constants |
| `frontMatter.ts` | YAML frontmatter parsing and serialization |
| `contentSanitizer.ts` | Content sanitization for generated output |
| `fileMapper.ts` | File discovery and mapping |
| `gitService.ts` | Git repository utilities |
| `promptLoader.ts` | Prompt template loading from `prompts/` directory |
| `versionChecker.ts` | npm registry version checking for update notifications |
| `prompts/` | Interactive prompt helpers (config summary, LLM config, analysis options) |

## Key architectural patterns

- **Dependency injection**: Services receive their dependencies (`ui`, `t`, `version`) via constructor options conforming to `BaseDependencies` or `AIDependencies` from `src/services/shared/types.ts`.
- **Service isolation**: Each feature lives in its own service directory with an index barrel export.
- **i18n throughout**: All user-facing strings go through the `TranslateFn` (`t`) function.
- **Zod validation**: MCP tool schemas and gateway parameters use Zod for runtime validation.


================================================
FILE: .context/docs/testing-strategy.md
================================================
---
type: doc
name: testing-strategy
description: Test frameworks, patterns, coverage requirements, and quality gates
category: testing
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Testing Strategy

This document describes the test infrastructure, conventions, and quality expectations for the `@dotcontext/cli` project.

## Test Types

### Unit tests

Unit tests validate individual functions, utilities, and service modules in isolation. They are the primary test type in this project.

**Examples of existing unit tests:**

- `src/utils/contentSanitizer.test.ts` -- content sanitization logic
- `src/utils/frontMatter.test.ts` -- YAML frontmatter parsing and serialization
- `src/utils/promptLoader.test.ts` -- prompt template loading
- `src/utils/versionChecker.test.ts` -- version comparison utilities

### Integration tests

Integration tests exercise larger slices of functionality, including CLI command execution and service orchestration.

**Examples:**

- `src/cli.test.ts` -- CLI command registration and execution
- `src/services/mcp/mcpServer.test.ts` -- MCP server registration and gateway behavior

## Framework & Configuration

| Setting              | Value                                        |
| -------------------- | -------------------------------------------- |
| Framework            | Jest 30.x                                    |
| TypeScript transform | ts-jest 29.x (`preset: 'ts-jest'`)           |
| Test environment     | Node                                         |
| Config file          | `jest.config.js`                             |

### File discovery

Jest is configured to find tests using two patterns:

- `**/__tests__/**/*.ts` -- tests inside `__tests__/` directories
- `**/?(*.)+(spec|test).ts` -- files ending in `.test.ts` or `.spec.ts`

All test roots are under `<rootDir>/src`. The `node_modules/` and `dist/` directories are excluded via `testPathIgnorePatterns`.

### Naming conventions

- Place unit tests alongside the source file: `src/utils/frontMatter.ts` -> `src/utils/frontMatter.test.ts`
- Use `.test.ts` for unit tests and `.integration.test.ts` for integration tests.
- Use `.spec.ts` when following a behavior-driven style (both are recognized).

## Running Tests

```bash
# Run the full test suite
npm test

# Run tests in watch mode (useful during development)
npx jest --watch

# Run a specific test file
npx jest src/utils/frontMatter.test.ts

# Run tests matching a pattern
npx jest --testPathPattern="utils"

# Run with coverage report
npx jest --coverage
```

### Coverage configuration

Coverage is collected from all `src/**/*.ts` files, excluding:

- Declaration files (`*.d.ts`)
- Index barrel files (`**/index.ts`)

Reports are generated in three formats:

| Format | Output                  | Purpose                    |
| ------ | ----------------------- | -------------------------- |
| `text` | Terminal                | Quick local feedback       |
| `lcov` | `coverage/lcov.info`   | CI integration, tooling    |
| `html` | `coverage/` directory  | Browsable detailed report  |

## Quality Gates

### Before merging a pull request

1. **All tests pass**: `npm test` must exit with code 0.
2. **No regressions**: Existing tests must not be removed or weakened without justification.
3. **New code has tests**: Features and bug fixes should include corresponding tests.
4. **Build succeeds**: `npm run build` must compile without TypeScript errors (test files are excluded from the build via `tsconfig.json`).

### Recommended coverage targets

While there is no enforced coverage threshold at this time, contributors should aim for:

- Utility functions: high coverage (these are pure and easy to test)
- Service modules: moderate coverage, focusing on core logic paths
- CLI integration: at least smoke-test-level coverage for new commands

## Troubleshooting

### Common issues

**ts-jest transform errors**

If you see transform errors, ensure `ts-jest` is installed and the Jest config specifies the correct transform:

```js
transform: {
  '^.+\\.ts$': 'ts-jest',
}
```

**Module resolution failures**

The project uses `baseUrl: "./src"` and path aliases in `tsconfig.json`. If Jest cannot resolve an import, check that `moduleFileExtensions` includes `ts` and `js`, and that the path alias is correctly mapped if applicable.

**Tree-sitter optional dependency warnings**

`tree-sitter` and `tree-sitter-typescript` are optional dependencies used for semantic analysis. Tests that depend on them may skip gracefully if the native modules are not installed. These warnings are safe to ignore in most development scenarios.

**Slow test runs**

`ts-jest` compiles TypeScript on the fly. For faster iteration, use `--watch` mode which only re-runs affected tests, or target a specific file with `npx jest <path>`.

**Integration test failures**

Integration tests that exercise MCP or workflow flows may create temporary files or directories. Ensure your working directory is clean and that no stale `.context` artifacts interfere with test expectations.


================================================
FILE: .context/docs/tooling.md
================================================
---
type: doc
name: tooling
description: Scripts, IDE settings, automation, and developer productivity tips
category: tooling
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Tooling & Productivity Guide

This document covers the scripts, tools, IDE configuration, and productivity practices used in the `@dotcontext/cli` project.

## Required Tooling

| Tool            | Version     | Purpose                                          |
| --------------- | ----------- | ------------------------------------------------ |
| Node.js         | >= 20.0.0   | Runtime for the CLI and all scripts               |
| npm             | (bundled)   | Package management and script execution           |
| TypeScript      | 5.x         | Language (strict mode, ES2020 target, CommonJS)   |
| tsx             | 4.x         | Fast TypeScript execution for development         |
| Git             | any recent  | Version control                                   |

### Optional tooling

| Tool                      | Purpose                                    |
| ------------------------- | ------------------------------------------ |
| tree-sitter (native)      | Semantic code analysis (optional dependency) |
| tree-sitter-typescript    | TypeScript grammar for tree-sitter          |

## npm Scripts Reference

All scripts are defined in `package.json`:

| Script              | Command                                           | Description                              |
| ------------------- | ------------------------------------------------- | ---------------------------------------- |
| `dev`               | `tsx src/index.ts`                                | Run CLI from source (no build step)       |
| `build`             | `tsc`                                             | Compile TypeScript to `dist/`             |
| `start`             | `node dist/index.js`                              | Run compiled CLI                          |
| `test`              | `jest`                                            | Run the full test suite                   |
| `prepublishOnly`    | `npm run build`                                   | Ensure a fresh build before publish       |
| `version`           | `npm run build`                                   | Rebuild on version bump                   |
| `release`           | `npm version patch && npm publish --access public`| Patch release to npm                      |
| `release:minor`     | `npm version minor && npm publish --access public`| Minor release to npm                      |
| `release:major`     | `npm version major && npm publish --access public`| Major release to npm                      |

## Recommended Automation

### Build and test workflow

A typical development cycle:

```bash
# 1. Start development (auto-reloads not built-in; re-run as needed)
npm run dev -- --help

# 2. Run tests after changes
npm test

# 3. Verify production build
npm run build && npm start -- --help
```

### Release workflow

```bash
# 1. Ensure main is up to date
git checkout main && git pull

# 2. Create a release branch
git checkout -b release/0.8.0

# 3. Update CHANGELOG.md

# 4. Run the release script (bumps version, builds, publishes)
npm run release:minor

# 5. Push tags and branch, then merge to main
git push --follow-tags
```

### Pre-commit checks

While the project does not currently enforce pre-commit hooks, the following manual checks are recommended before every commit:

```bash
npm test && npm run build
```

Consider adding [husky](https://typicode.github.io/husky/) and [lint-staged](https://github.com/lint-staged/lint-staged) if the team wants automated pre-commit enforcement.

## IDE Setup

### VS Code (recommended)

**Suggested extensions:**

- **TypeScript** -- built-in, ensure workspace TypeScript version matches (`5.x`)
- **ESLint** -- if a linter config is added in the future
- **Jest Runner** -- run individual tests from the editor
- **Prettier** -- consistent formatting (configure to match project style)

**Recommended `settings.json` overrides:**

```jsonc
{
  "typescript.tsdk": "node_modules/typescript/lib",
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "jest.jestCommandLine": "npx jest"
}
```

### Other editors

- **WebStorm/IntelliJ**: TypeScript support is built-in. Configure the Jest run configuration to use the project's `jest.config.js`.
- **Vim/Neovim**: Use `coc-tsserver` or `nvim-lspconfig` with `ts_ls` for TypeScript language support. Run tests via terminal.

## TypeScript Configuration Highlights

Key `tsconfig.json` settings that affect the development experience:

| Setting                        | Value        | Impact                                     |
| ------------------------------ | ------------ | ------------------------------------------ |
| `strict`                       | `true`       | Full strict type checking enabled           |
| `target`                       | `ES2020`     | Modern JS features available                |
| `module`                       | `commonjs`   | Compatible with Node.js require()           |
| `declaration` / `declarationMap` | `true`     | Type declarations emitted for consumers     |
| `sourceMap`                    | `true`       | Enables debugger source mapping             |
| `baseUrl`                      | `./src`      | Short imports from src root                 |
| `paths`                        | configured   | `@generators/agents/*` alias available      |

Test files (`**/*.test.ts`) are excluded from the build output but included in the IDE's type checking.

## Productivity Tips

1. **Use `npm run dev` for fast iteration.** The `tsx` runner executes TypeScript directly without a build step, making the feedback loop much faster than `build` + `start`.

2. **Target specific tests.** Instead of running the full suite, use `npx jest <file>` or `npx jest --watch` to focus on what you are changing.

3. **Leverage the `--help` flag.** Every CLI command supports `--help` for discoverability: `npm run dev -- workflow --help`.

4. **Use MCP for context creation and AI generation.** Standalone CLI generation is no longer supported. Install MCP with `npx -y @dotcontext/cli@latest mcp:install` and use your AI tool to create, fill, or refresh context.

5. **Read the generated context.** After initializing context through MCP, browse `.context/docs/` and `.context/agents/` to understand what the tool produces -- this helps when working on generators and templates.

6. **Check `codebase-map.json` for navigation.** The file at `.context/docs/codebase-map.json` provides a structural overview of the entire codebase, useful for orienting yourself in unfamiliar areas.

7. **Debug with source maps.** Since `sourceMap: true` is configured, you can attach a Node.js debugger to the compiled output and step through the original TypeScript source.


================================================
FILE: .context/skills/README.md
================================================
# Skills

On-demand expertise for AI agents. Skills are task-specific procedures that get activated when relevant.

> Project: dotcontext

## How Skills Work

1. **Discovery**: AI agents discover available skills via the `skill` MCP tool or by reading this directory
2. **Matching**: When a task matches a skill's description, it gets activated
3. **Execution**: The skill's instructions guide the AI's behavior with project-specific procedures

## Available Skills

### Built-in Skills

| Skill | Description | Phases | Status |
|-------|-------------|--------|--------|
| [MCP Tool Design](./api-design/SKILL.md) | Design MCP tools and gateway interfaces for the dotcontext server | P, R | filled |
| [Bug Investigation](./bug-investigation/SKILL.md) | Systematic bug investigation and root cause analysis | E, V | filled |
| [Code Review](./code-review/SKILL.md) | Review code quality, patterns, and best practices | R, V | filled |
| [Commit Message](./commit-message/SKILL.md) | Generate commit messages following conventional commits with scope detection | E, C | filled |
| [Documentation](./documentation/SKILL.md) | Generate and update technical documentation | P, C | filled |
| [Feature Breakdown](./feature-breakdown/SKILL.md) | Break down features into implementable tasks | P | filled |
| [PR Review](./pr-review/SKILL.md) | Review pull requests against team standards and best practices | R, V | filled |
| [Refactoring](./refactoring/SKILL.md) | Safe code refactoring with step-by-step approach | E | filled |
| [Security Audit](./security-audit/SKILL.md) | Security review checklist for code and infrastructure | R, V | filled |
| [Test Generation](./test-generation/SKILL.md) | Generate comprehensive test cases for code | E, V | filled |

## Creating Custom Skills

Create a new skill by adding a directory with a `SKILL.md` file:

```
.context/skills/
└── my-skill/
    ├── SKILL.md          # Required: skill definition
    └── templates/        # Optional: helper resources
        └── checklist.md
```

### SKILL.md Format

```yaml
---
type: skill
name: my-skill
description: When to use this skill
skillSlug: my-skill
phases: [P, E, V]  # Optional: PREVC phases
mode: false        # Optional: mode command?
status: filled
scaffoldVersion: "2.0.0"
---

# My Skill

## When to Use
[Description of when this skill applies]

## Instructions
1. Step one
2. Step two

## Examples
[Usage examples]
```

## PREVC Phase Mapping

| Phase | Name | Skills |
|-------|------|--------|
| P | Planning | feature-breakdown, documentation, api-design (MCP tool design) |
| R | Review | pr-review, code-review, api-design (MCP tool design), security-audit |
| E | Execution | commit-message, test-generation, refactoring, bug-investigation |
| V | Validation | pr-review, code-review, test-generation, bug-investigation, security-audit |
| C | Confirmation | commit-message, documentation |

## Accessing Skills Programmatically

Via MCP tools:
- `skill({ action: 'list' })` -- List all skills
- `skill({ action: 'getContent', skillSlug: 'code-review' })` -- Get skill content
- `skill({ action: 'getForPhase', phase: 'E' })` -- Get skills for a PREVC phase

Via the SkillRegistry (`src/workflow/skills/skillRegistry.ts`):
- Discovers built-in and custom skills from `.context/skills/`
- Parses YAML frontmatter and markdown content
- Used by MCP gateway handler in `src/services/mcp/gateway/skill.ts`


================================================
FILE: .context/skills/api-design/SKILL.md
================================================
---
type: skill
name: MCP Tool Design
description: Design MCP tools and gateway interfaces for the dotcontext server
skillSlug: api-design
phases: [P, R]
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# MCP Tool Design

Guidance for designing and extending MCP (Model Context Protocol) tools exposed by `AIContextMCPServer` in `src/services/mcp/mcpServer.ts`.

## When to Use

- Adding a new MCP tool or gateway action to the server
- Refactoring the existing 9-tool surface (5 consolidated gateways + 4 dedicated workflow tools)
- Changing Zod input schemas for existing tools
- Adding new resource templates (e.g., `context://`, `file://`, `workflow://`)
- Designing a new gateway handler in `src/services/mcp/gateway/`

## Architecture Overview

The MCP server follows a **consolidated gateway** pattern to minimize cognitive load for AI agents:

```
AIContextMCPServer (mcpServer.ts)
  registerGatewayTools()
    -> explore     (read, list, analyze, search, getStructure)
    -> context     (check, init, fill, fillSingle, listToFill, getMap, buildSemantic, scaffoldPlan)
    -> sync        (exportRules, exportDocs, exportAgents, exportContext, exportSkills, reverseSync, importDocs, importAgents, importSkills)
    -> plan        (link, getLinked, getDetails, getForPhase, updatePhase, recordDecision, updateStep, getStatus, syncMarkdown, commitPhase)
    -> agent       (discover, getInfo, orchestrate, getSequence, getDocs, getPhaseDocs, listTypes)
    -> skill       (list, getContent, getForPhase, scaffold, export, fill)
    -> workflow-init / workflow-status / workflow-advance / workflow-manage
```

Each gateway dispatches to a handler in `src/services/mcp/gateway/<name>.ts`. The handler receives typed params and an options object with `repoPath`.

## Instructions

### 1. Decide: New Gateway vs. New Action

- **New action on existing gateway**: Preferred. Add an action variant to the existing `z.enum([...])` and extend the handler switch.
- **New dedicated tool**: Only when the domain is distinct enough to warrant its own tool (like `workflow-*` was split out for clarity).
- **Rule of thumb**: Keep the total tool count under 12 to avoid overwhelming AI agent tool selection.

### 2. Define the Input Schema with Zod

All MCP tool inputs use Zod v4 schemas (imported from `zod`). Follow the existing pattern:

```typescript
inputSchema: {
  action: z.enum(['existingAction', 'newAction'])
    .describe('Action to perform'),
  newParam: z.string().optional()
    .describe('(newAction) What this param does'),
}
```

Key conventions:
- Every parameter gets a `.describe()` with the action prefix in parentheses: `(actionName)`
- Use `z.enum()` for constrained values, `z.array(z.string())` for lists
- Mark all action-specific params as `.optional()` since different actions use different params
- Import shared enums from `../../workflow` (e.g., `PREVC_ROLES`, `AGENT_TYPES`)

### 3. Create the Gateway Handler

Add a new file in `src/services/mcp/gateway/` or extend an existing one:

```typescript
// src/services/mcp/gateway/myGateway.ts
import { createJsonResponse, createErrorResponse, type MCPToolResponse } from './response';

export type MyAction = 'doThing' | 'doOther';

export interface MyParams {
  action: MyAction;
  repoPath?: string;
  // action-specific params
}

export interface MyOptions {
  repoPath: string;
}

export async function handleMy(params: MyParams, options: MyOptions): Promise<MCPToolResponse> {
  switch (params.action) {
    case 'doThing':
      return createJsonResponse({ success: true, message: 'Done' });
    default:
      return createErrorResponse(`Unknown action: ${params.action}`);
  }
}
```

### 4. Response Format

Use the three helpers from `src/services/mcp/gateway/response.ts`:
- `createJsonResponse(data)` -- structured JSON for programmatic consumption
- `createErrorResponse(message)` -- sets `isError: true`
- `createTextResponse(text)` -- plain text for human-readable output

All responses conform to `MCPToolResponse` with `content: [{ type: 'text', text }]`.

### 5. Wire It Up in mcpServer.ts

Register the tool in `registerGatewayTools()` using the `wrap()` helper for automatic action logging:

```typescript
this.server.registerTool('my-tool', {
  description: `Description with action list...`,
  inputSchema: { /* Zod schemas */ }
}, wrap('my-tool', async (params): Promise<MCPToolResponse> => {
  return handleMy(params as MyParams, { repoPath: this.getRepoPath() });
}));
```

### 6. Re-export from gatewayTools.ts

Add your handler, types, and params to the re-export barrel in `src/services/mcp/gatewayTools.ts` and `src/services/mcp/gateway/index.ts`.

### 7. Test

Write tests in `src/services/mcp/` following the pattern in `mcpServer.test.ts`. Since MCP tools require stdio transport, test the handler functions directly:

```typescript
import { handleMy } from './gateway/myGateway';

it('should handle doThing action', async () => {
  const result = await handleMy(
    { action: 'doThing' },
    { repoPath: tempDir }
  );
  const payload = JSON.parse(result.content[0].text);
  expect(payload.success).toBe(true);
});
```

## Design Checklist

- [ ] Action names are verbs or verb phrases (e.g., `getStatus`, `buildSemantic`, `exportRules`)
- [ ] All params have `.describe()` annotations with action prefix
- [ ] Handler returns `MCPToolResponse` via response helpers
- [ ] `repoPath` resolution uses `this.getRepoPath(params.repoPath)` for caching
- [ ] Tool description includes a complete action list for AI discoverability
- [ ] New types are exported through the gateway barrel file
- [ ] Action logging works via the `wrap()` helper
- [ ] Total tool count stays manageable (currently 9)

## Common Pitfalls

- **Do not** use `process.cwd()` directly in handlers; always use the `repoPath` from options
- **Do not** add required params that are only needed for one action; use `.optional()` and validate inside the handler
- **Do not** return raw errors; wrap them with `createErrorResponse()` for consistent error shape
- **Do not** log to stdout in MCP mode; use `process.stderr.write()` to avoid corrupting the MCP protocol


================================================
FILE: .context/skills/bug-investigation/SKILL.md
================================================
---
type: skill
name: Bug Investigation
description: Systematic bug investigation and root cause analysis
skillSlug: bug-investigation
phases: [E, V]
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Bug Investigation

Systematic approach to investigating and fixing bugs in the `@dotcontext/cli` CLI tool.

## When to Use

- A CLI command (`workflow`, `sync`, `mcp`, etc.) produces incorrect output or crashes
- An MCP tool returns an error or unexpected response
- Semantic analysis (tree-sitter / LSP) fails on certain codebases
- Scaffold generation produces malformed frontmatter or missing content
- Workflow phase transitions behave incorrectly
- Tests fail unexpectedly after changes

## Project-Specific Investigation Surfaces

| Area | Key Files | Common Issues |
|------|-----------|---------------|
| CLI commands | `src/index.ts`, `src/services/*/index.ts` | Commander option parsing, missing args |
| MCP server | `src/services/mcp/mcpServer.ts`, `src/services/mcp/gateway/*.ts` | repoPath resolution, Zod validation failures |
| Scaffold generation | `src/generators/*/`, `src/types/scaffoldFrontmatter.ts` | Frontmatter parsing, file path resolution |
| Scaffold fill via MCP | `src/services/ai/tools/fillScaffoldingTool.ts`, `src/services/mcp/gateway/context.ts` | Missing files, stale context, oversized responses |
| Semantic analysis | `src/services/semantic/codebaseAnalyzer.ts`, `src/services/semantic/treeSitter/` | tree-sitter optional dep missing, parse failures |
| Workflow | `src/workflow/`, `src/services/workflow/workflowService.ts` | Phase transition logic, gate checking |
| i18n | `src/utils/i18n.ts` | Missing translation keys, locale detection |
| Frontmatter | `src/utils/frontMatter.ts` | v1 vs v2 format confusion, status detection |

## Instructions

### 1. Reproduce the Bug

Run the CLI in dev mode to reproduce:

```bash
# Direct execution via tsx
npx tsx src/index.ts workflow --help

# For MCP-related bugs, capture stderr output
npx tsx src/index.ts mcp --verbose 2>mcp-debug.log
```

For MCP tool bugs, test the gateway handler directly in a script or test file rather than through the full MCP transport.

### 2. Identify the Service Layer

Trace the call path from the CLI command or MCP tool to the responsible service:

```
CLI command (src/index.ts)
  -> Service (src/services/<domain>/)
    -> Generator (src/generators/) or Util (src/utils/)
```

For MCP:
```
MCP tool (mcpServer.ts registerGatewayTools)
  -> Gateway handler (src/services/mcp/gateway/<tool>.ts)
    -> Service (src/services/<domain>/)
```

### 3. Check Known Fragile Points

- **Optional dependencies**: `tree-sitter` and `tree-sitter-typescript` are in `optionalDependencies`. Code must handle their absence gracefully. Check `src/services/semantic/treeSitter/treeSitterLayer.ts`.
- **repoPath resolution**: The MCP server has a 4-level priority: explicit param > cached path > initial path > `process.cwd()`. Bugs often arise from incorrect path resolution. See `getRepoPath()` in `mcpServer.ts`.
- **Frontmatter parsing**: Two formats exist (v1 simple, v2 scaffold). Check `src/utils/frontMatter.ts` and `isScaffoldFrontmatter()`.
- **Provider/default detection**: Local model defaults are derived from `src/services/ai/providerFactory.ts` and `src/utils/prompts/smartDefaults.ts`. MCP-hosted generation usually relies on the connected tool's model.
- **File path handling**: Always use `path.resolve()` or `path.join()`. Watch for relative vs. absolute path confusion, especially in `contextBuilder.ts`.

### 4. Use Existing Tests as Reference

Run the relevant test suite to see what is expected:

```bash
# Run all tests
npm test

# Run specific test file
npx jest src/services/mcp/mcpServer.test.ts

# Run tests matching a pattern
npx jest --testPathPattern="mcp"
```

Key test files:
- `src/services/mcp/mcpServer.test.ts` -- MCP server instantiation
- `src/services/mcp/mcpServer.test.ts` -- MCP tool registration and dispatch
- `src/services/semantic/codebaseAnalyzer.test.ts` -- Semantic analysis
- `src/utils/frontMatter.test.ts` -- Frontmatter parsing
- `src/utils/contentSanitizer.test.ts` -- Content sanitization
- `src/workflow/gates/gateChecker.test.ts` -- Workflow gate logic

### 5. Isolate with Logging

The project uses `ora` for spinners and `chalk` for colored output. For debugging:
- CLI: Pass `--verbose` flag to enable detailed logging
- MCP: The `log()` method writes to `process.stderr` when `verbose: true`
- Services: Add temporary `console.error()` calls (never `console.log()` in MCP mode)

### 6. Fix and Verify

After identifying root cause:

1. Write a failing test that demonstrates the bug
2. Apply the fix in the appropriate service/util
3. Run the full test suite: `npm test`
4. Run the CLI manually to verify end-to-end: `npx tsx src/index.ts <command>`
5. Check TypeScript compilation: `npm run build`

## Common Bug Patterns

### "Cannot find module" at Runtime
- Check if the import uses the `@generators/agents/*` path alias (defined in `tsconfig.json`)
- Ensure the file is not excluded from compilation by `tsconfig.json`

### MCP Tool Returns Unexpected Error
- Check Zod schema validation in `mcpServer.ts` -- params may not match the schema
- Check the gateway handler's switch statement for unhandled actions
- Verify `repoPath` resolves to a directory with `.context/` scaffolding

### Frontmatter Status Not Detected
- v2 scaffold files use `scaffoldVersion: "2.0.0"` and `status: unfilled|filled`
- Ensure `isScaffoldFrontmatter()` check happens before v1 fallback
- Check for BOM or encoding issues in the file header

### Workflow Phase Transition Fails
- Check gate configuration in `src/workflow/gates/`
- Verify scale-dependent phase skipping (QUICK skips P and R)
- Check `src/workflow/prevcConfig.ts` for scale definitions

### MCP Scaffold Fill Produces Empty or Placeholder Guidance
- Verify `fillSingleFileTool` can read the scaffold and build semantic context
- Check scaffold structure registration via `getScaffoldStructure()`
- Confirm `SemanticContextBuilder` is returning project-specific content
- Check response size and cached-context invalidation behavior


================================================
FILE: .context/skills/code-review/SKILL.md
================================================
---
type: skill
name: Code Review
description: Review code quality, patterns, and best practices
skillSlug: code-review
phases: [R, V]
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Code Review

Guidelines for reviewing code changes in the `@dotcontext/cli` project.

## When to Use

- Reviewing a pull request or diff
- Validating code during the Review (R) or Validation (V) phases of the PREVC workflow
- Checking a new service, generator, or utility for adherence to project patterns
- Evaluating MCP gateway handler implementations

## Project Standards

### TypeScript Configuration

- Target: ES2020, Module: CommonJS
- Strict mode enabled (`"strict": true`)
- Declarations and source maps generated
- Path alias: `@generators/agents/*` maps to `src/generators/agents/*`

### Code Organization Patterns

**Service Layer** (22 services in `src/services/`):
- Each service lives in its own directory under `src/services/`
- Exports through `index.ts` barrel files
- Constructor takes an options object or required config
- Methods are async where I/O is involved
- Example: `FillService`, `WorkflowService`, `AIContextMCPServer`

**Generators** (`src/generators/`):
- Separate generators for docs, agents, plans, skills
- Accept options objects, return typed result objects (e.g., `SkillGeneratorResult`)
- Use frontmatter serialization from `src/types/scaffoldFrontmatter.ts`

**Utilities** (`src/utils/`):
- Pure functions or thin wrappers: `frontMatter.ts`, `contentSanitizer.ts`, `gitService.ts`
- CLI UI abstraction: `cliUI.ts` with `CLIInterface` type
- i18n: `i18n.ts` with `TranslateFn` type and `en`/`pt-BR` locale support

**MCP Gateway Handlers** (`src/services/mcp/gateway/`):
- One file per gateway: `explore.ts`, `context.ts`, `sync.ts`, etc.
- Exports: handler function, params type, options type, action type
- Uses `createJsonResponse`/`createErrorResponse`/`createTextResponse` from `response.ts`
- Barrel re-export through `index.ts` and `gatewayTools.ts`

### Review Checklist

#### Architecture

- [ ] New code follows the service/generator/util separation
- [ ] No direct file I/O in generators -- delegate to services or `fs-extra`
- [ ] MCP handlers do not use `console.log` (use `process.stderr.write` for debug output)
- [ ] `repoPath` is never hardcoded; always resolved through options or `getRepoPath()`

#### TypeScript Quality

- [ ] No `any` types (use `unknown` + type guards where needed)
- [ ] Exported interfaces/types for all public APIs
- [ ] Async functions return typed Promises, not implicit `any`
- [ ] Optional dependencies (tree-sitter) have graceful fallbacks

#### Error Handling

- [ ] MCP gateway handlers return `createErrorResponse()` rather than throwing
- [ ] CLI commands catch errors and display via `chalk`/`ora` with user-friendly messages
- [ ] File operations use `fs-extra` methods which handle missing directories

#### Naming Conventions

- [ ] Files: camelCase (`fillService.ts`, `codebaseAnalyzer.ts`)
- [ ] Classes: PascalCase (`SkillGenerator`, `SemanticContextBuilder`)
- [ ] Interfaces: PascalCase, often with `I`-free naming (`SkillMetadata`, not `ISkillMetadata`)
- [ ] Constants: UPPER_SNAKE_CASE (`BUILT_IN_SKILLS`, `PREVC_PHASE_ORDER`)
- [ ] MCP tools: kebab-case (`workflow-init`, `workflow-status`)

#### Testing

- [ ] New services have corresponding `.test.ts` files
- [ ] Tests use `jest.mock()` for external dependencies (AI providers, file system)
- [ ] Temp directories created with `fs.mkdtemp()` and cleaned up in `afterEach`
- [ ] Mock `CLIInterface` and `TranslateFn` for service tests (see `fillService.test.ts`)

#### Frontmatter

- [ ] New scaffold files use v2 format with `scaffoldVersion: "2.0.0"`
- [ ] `status` field is set correctly (`unfilled` for new, `filled` after content generation)
- [ ] Type-specific fields present (`skillSlug` for skills, `agentType` for agents, etc.)

#### i18n

- [ ] New user-facing strings added to both `en` and `pt-BR` in `src/utils/i18n.ts`
- [ ] Translation keys follow dot-notation: `'commands.fill.description'`
- [ ] CLI output uses `t()` function, not hardcoded strings

## Instructions

### Reviewing a Service Change

1. Check the service's public interface -- does it follow the options-object constructor pattern?
2. Verify barrel exports in `index.ts` are updated
3. Check for proper error handling (try/catch with typed errors)
4. Ensure no side effects in constructors (async init should be a separate method)
5. Look for dependency injection points (e.g., `AIContextMCPServer` accepts `contextBuilder` for testing)

### Reviewing an MCP Tool Change

1. Verify Zod schema has `.describe()` on every param with action prefix
2. Check that the handler switch covers all actions in the enum
3. Confirm responses use `createJsonResponse`/`createErrorResponse` consistently
4. Verify new types are re-exported through `gatewayTools.ts`
5. Check that `repoPath` uses the caching mechanism via `getRepoPath()`

### Reviewing a Generator Change

1. Check output paths are constructed with `path.join(repoPath, outputDir, ...)`
2. Verify `force` flag is respected (skip existing files when `false`)
3. Ensure frontmatter is generated via `createSkillFrontmatter`/`serializeFrontmatter` from `scaffoldFrontmatter.ts`
4. Check that the result type includes all relevant counts (generated, skipped, etc.)

### Reviewing a Workflow Change

1. Verify phase transitions follow PREVC order (P -> R -> E -> V -> C)
2. Check scale-dependent phase inclusion (QUICK: E+V only, SMALL: P+E+V, MEDIUM: P+R+E+V, LARGE: all)
3. Ensure gate checks are enforced unless `autonomous` or `force` is true
4. Verify workflow status file is written to `.context/workflow/`


================================================
FILE: .context/skills/commit-message/SKILL.md
================================================
---
type: skill
name: Commit Message
description: Generate commit messages following conventional commits with scope detection
skillSlug: commit-message
phases: [E, C]
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Commit Message

Generate consistent, informative commit messages for the `@dotcontext/cli` project.

## When to Use

- Committing code during the Execution (E) or Confirmation (C) phases
- After completing a feature, bug fix, or refactoring task
- When using the `plan({ action: 'commitPhase' })` MCP tool to auto-commit phase outputs

## Commit Format

This project follows **Conventional Commits** with scope detection:

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

### Types

| Type | Use When |
|------|----------|
| `feat` | Adding new functionality (new MCP tool, new generator, new CLI command) |
| `fix` | Fixing a bug (broken scaffold generation, incorrect path resolution) |
| `refactor` | Restructuring code without changing behavior (service extraction, gateway consolidation) |
| `docs` | Documentation only (README, CHANGELOG, `.context/` content) |
| `test` | Adding or updating tests |
| `chore` | Build, tooling, dependency updates |
| `ci` | CI/CD configuration |

### Scopes

Derive scope from the primary area of change:

| Scope | Directory/Area |
|-------|---------------|
| `mcp` | `src/services/mcp/` -- MCP server, gateway tools |
| `cli` | `src/index.ts` -- CLI commands, commander setup |
| `context` | `src/services/ai/tools/`, `src/services/init/` -- MCP scaffold and semantic-context flows |
| `init` | `src/services/init/` -- Scaffold initialization |
| `sync` | `src/services/sync/`, `src/services/export/`, `src/services/import/` |
| `semantic` | `src/services/semantic/` -- Tree-sitter, LSP, codebase analysis |
| `workflow` | `src/workflow/`, `src/services/workflow/` -- PREVC phases, gates |
| `generators` | `src/generators/` -- Doc, agent, plan, skill generators |
| `skills` | `src/workflow/skills/`, `.context/skills/` |
| `agents` | `src/generators/agents/`, `.context/agents/` |
| `plans` | `src/generators/plans/`, `src/services/mcp/gateway/plan.ts`, `.context/plans/` |
| `i18n` | `src/utils/i18n.ts` -- Translations |
| `utils` | `src/utils/` -- Frontmatter, git, CLI UI |
| `ai` | `src/services/ai/` -- AI SDK, providers, tools |
| `types` | `src/types/`, `src/types.ts` -- Type definitions |
| `deps` | `package.json` -- Dependency changes |

When changes span multiple scopes, use the most significant one or omit the scope.

## Instructions

### 1. Analyze the Diff

Look at what changed:
- Which services/files are modified?
- Is this a new feature, a fix, or a refactor?
- Does it touch user-facing behavior (CLI output, MCP responses)?

### 2. Choose Type and Scope

```
# New MCP gateway action
feat(mcp): add buildSemantic action to context gateway

# Bug fix in scaffold generation
fix(generators): handle missing frontmatter in skill scaffold files

# Refactoring workflow internals
refactor(workflow): extract gate checking into separate GateChecker class

# Updating translations
feat(i18n): add pt-BR translations for workflow status messages
```

### 3. Write the Description

- Use imperative mood ("add", "fix", "update", not "added", "fixes")
- Keep under 72 characters
- Focus on **what** changed and **why**, not implementation details
- Reference the affected MCP tool or CLI command when relevant

### 4. Add Body for Complex Changes

For multi-file changes, include context:

```
feat(mcp): add skill management gateway with 6 actions

Add the `skill` gateway tool to the MCP server with actions:
list, getContent, getForPhase, scaffold, export, fill.

Includes Zod schema validation, action logging via wrap(),
and barrel re-exports through gatewayTools.ts.
```

### 5. Add Footer When Applicable

```
# Breaking change
feat(mcp)!: consolidate project tools into context gateway

BREAKING CHANGE: Removed standalone project-setup and project-report
tools. Use context({ action: "init" }) and workflow-init instead.

# Issue reference
fix(semantic): handle missing tree-sitter gracefully

Closes #31

# Co-authored commits (used by plan commitPhase)
feat(workflow): implement PREVC phase auto-advance

Co-Authored-By: feature-developer <agent@ai-coders>
```

## Examples

```bash
# Small fix
git commit -m "fix(frontmatter): detect v2 scaffold format before v1 fallback"

# New feature
git commit -m "feat(mcp): add plan commitPhase action for git integration"

# Dependency update
git commit -m "chore(deps): upgrade @modelcontextprotocol/sdk to 1.25.2"

# Documentation
git commit -m "docs(skills): fill bug-investigation skill with project-specific content"

# Test addition
git commit -m "test(context): cover fillSingle guidance for generated scaffolds"

# Multi-scope refactor
git commit -m "refactor: extract gateway handlers into individual modules"
```

## PREVC Phase Commits

When using the plan tool's `commitPhase` action, commits are auto-generated with:
- Stage patterns defaulting to `[".context/**"]`
- Co-Author footer from the agent name
- Message format: `<type>(<scope>): complete <phase> phase for <plan>`

For manual phase commits, follow the same pattern:

```
feat(workflow): complete Planning phase for add-caching-layer

- Created PRD and tech spec in .context/plans/
- Defined acceptance criteria and test plan
- Linked plan to active workflow

Co-Authored-By: planner <agent@ai-coders>
```


================================================
FILE: .context/skills/documentation/SKILL.md
================================================
---
type: skill
name: Documentation
description: Generate and update technical documentation
skillSlug: documentation
phases: [P, C]
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Documentation

Guidelines for creating and maintaining documentation in the `@dotcontext/cli` project.

## When to Use

- Planning phase (P): Writing PRDs, tech specs, or architecture docs in `.context/plans/`
- Confirmation phase (C): Updating project docs after feature completion
- Filling scaffold documentation files in `.context/docs/`
- Updating the README, CHANGELOG, or CONTRIBUTING guides
- Writing or updating `.context/` content (docs, agents, skills, plans)

## Documentation Locations

| Location | Purpose | Format |
|----------|---------|--------|
| `.context/docs/` | Project knowledge base (generated scaffolds) | Markdown with YAML frontmatter |
| `.context/agents/` | AI agent playbooks | Markdown with YAML frontmatter |
| `.context/skills/` | On-demand expertise guides | Markdown with YAML frontmatter |
| `.context/plans/` | Feature plans and tracking | Markdown with YAML frontmatter |
| `README.md` | Public-facing project overview | Standard Markdown |
| `CHANGELOG.md` | Version history (Keep a Changelog format) | Standard Markdown |
| `CONTRIBUTING.md` | Contributor guidelines | Standard Markdown |
| `AGENTS.md` | Agent knowledge base reference | Standard Markdown |
| `CLAUDE.md` | Claude-specific project instructions | Standard Markdown |

## Instructions

### Updating Scaffold Documentation (.context/docs/)

Scaffold docs use v2 frontmatter:

```yaml
---
type: documentation
name: Project Overview
description: High-level project summary
category: core
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---
```

Core docs in this project:
- `project-overview.md` -- Technology stack, entry points, getting started
- `development-workflow.md` -- Branching, CI, contributing process
- `testing-strategy.md` -- Jest config, test types, quality gates
- `tooling.md` -- CLI scripts, dev commands, IDE setup
- `codebase-map.json` -- Auto-generated semantic analysis output

When updating, preserve the frontmatter and set `status: filled`.

### Writing Agent Playbooks (.context/agents/)

Each playbook follows this structure:
1. **Mission** -- When to use this agent
2. **Responsibilities** -- Concrete task list
3. **Best Practices** -- Project-specific guidelines
4. **Collaboration Checklist** -- Step-by-step workflow

Available agents: `code-reviewer`, `bug-fixer`, `feature-developer`, `refactoring-specialist`, `test-writer`, `documentation-writer`, `performance-optimizer`.

### Writing Skill Guides (.context/skills/)

Skills use this structure:
1. **When to Use** -- Activation triggers
2. **Instructions** -- Step-by-step procedure
3. **Examples** -- Concrete, project-specific examples
4. **Checklist or Guidelines** -- Quick reference

### Updating CHANGELOG.md

Follow Keep a Changelog format. Group changes under version headers:

```markdown
## [0.7.2]

### Included Pull Requests
- [#XX](url) - type: description

### Added
- **Feature Name**: Details

### Changed
- **Area**: What changed

### Fixed
- **Bug**: What was fixed
```

### Writing Plan Documents (.context/plans/)

Plans are created via `context({ action: 'scaffoldPlan', planName: '...' })` or manually. Structure:

```markdown
---
type: plan
name: feature-name
planSlug: feature-name
status: active
---

# Feature Name

## Goal
What this achieves.

## Phases
### Phase 1: Planning
- [ ] Step 1
- [ ] Step 2

### Phase 2: Execution
- [ ] Step 1
```

## Content Guidelines

### For This Project Specifically

- Reference actual file paths: `src/services/mcp/mcpServer.ts`, not "the MCP server file"
- Use the project's terminology: "scaffolding" (not "templates"), "fill" (not "populate"), "gateway" (not "endpoint")
- Include CLI commands with the dev runner: `npx tsx src/index.ts <command>`
- Reference PREVC phases by letter and name: "Execution (E) phase"
- Mention the 9-tool MCP surface when discussing architecture
- Note Node >= 20 requirement and TypeScript strict mode

### Formatting Standards

- Use tables for structured comparisons
- Use code blocks with language tags for all code samples
- Keep paragraphs short (3-4 sentences max)
- Use headings to create scannable structure
- Frontmatter must be valid YAML between `---` delimiters

### i18n Awareness

- User-facing CLI strings should reference translation keys from `src/utils/i18n.ts`
- Documentation itself is written in English
- The project supports `en` and `pt-BR` locales

## Generating Documentation via MCP

Standalone CLI AI generation is not supported. Documentation completion flows through MCP:

- `context({ action: 'fillSingle', filePath: '/path/to/doc.md' })` -- returns semantic context and scaffold structure for one file
- `context({ action: 'fill', target: 'docs' })` -- returns batched guidance for multiple scaffold files
- `src/services/autoFill/autoFillService.ts` -- provides static starter content during scaffold generation

The MCP fill process:
1. Generates scaffolding through `context({ action: 'init' })`
2. Builds semantic context via `SemanticContextBuilder`
3. Returns scaffold structure and instructions to the connected AI tool
4. Lets the MCP client generate and write the final content
5. Updates the frontmatter to `status: filled`


================================================
FILE: .context/skills/feature-breakdown/SKILL.md
================================================
---
type: skill
name: Feature Breakdown
description: Break down features into implementable tasks
skillSlug: feature-breakdown
phases: [P]
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# Feature Breakdown

Break down features into concrete, implementable tasks within the `@dotcontext/cli` architecture.

## When to Use

- Starting the Planning (P) phase of a PREVC workflow
- Scoping a new CLI command, MCP tool, or service
- Creating a plan document in `.context/plans/`
- Estimating complexity to choose the right workflow scale (QUICK/SMALL/MEDIUM/LARGE)

## Instructions

### 1. Classify the Feature Scope

Determine which layers of the codebase are involved:

| Layer | Directory | Examples |
|-------|-----------|----------|
| CLI | `src/index.ts` | New command, new flag, output format change |
| Service | `src/services/<domain>/` | New business logic, data processing |
| Generator | `src/generators/` | New scaffold type, template changes |
| MCP | `src/services/mcp/` | New tool, new gateway action, schema change |
| Workflow | `src/workflow/` | Phase logic, gate rules, skill/agent integration |
| Utils | `src/utils/` | New utility function, i18n keys, CLI UI changes |
| Types | `src/types/`, `src/types.ts` | New interfaces, frontmatter types |

### 2. Determine the Workflow Scale

Use these criteria to set the `scale` when calling `workflow-init`:

| Scale | Criteria | Typical Feature |
|-------|----------|-----------------|
| QUICK | Single file, no design decisions | Fix typo, update translation key |
| SMALL | 2-5 files, straightforward logic | Add a flag to existing CLI command |
| MEDIUM | Multiple services, design decisions needed | New MCP gateway action with service |
| LARGE | New subsystem, cross-cutting concerns | New generator type, new AI provider |

### 3. Identify the Task Breakdown Pattern

Most features in this project follow one of these patterns:

#### Pattern A: New MCP Gateway Action
1. Define the action in the Zod schema (`mcpServer.ts`)
2. Add handler logic in the gateway file (`src/services/mcp/gateway/<tool>.ts`)
3. Create or extend the backing service (`src/services/<domain>/`)
4. Update type exports in `gatewayTools.ts` and `gateway/index.ts`
5. Add tests for the handler
6. Update MCP tool description string

#### Pattern B: New CLI Command
1. Define the command with Commander in `src/index.ts`
2. Create the service in `src/services/<name>/`
3. Add i18n keys to `src/utils/i18n.ts` (both `en` and `pt-BR`)
4. Wire CLI options to service calls
5. Add CLI output via `CLIInterface` from `src/utils/cliUI.ts`
6. Write tests

#### Pattern C: New Generator/Scaffold Type
1. Create generator class in `src/generators/<type>/`
2. Define templates in `src/generators/<type>/templates/`
3. Add frontmatter type to `src/types/scaffoldFrontmatter.ts`
4. Integrate with `InitService` for scaffold creation
5. Integrate with `FillService` for AI content generation
6. Add to MCP context gateway if applicable
7. Write generator tests

#### Pattern D: New Workflow Feature
1. Update types in `src/workflow/types.ts`
2. Modify phase/gate logic in `src/workflow/`
3. Update `WorkflowService` in `src/services/workflow/`
4. Update MCP workflow tools if user-facing
5. Write tests for phase transitions

### 4. Create the Plan Document

Use the MCP tool or create manually:

```bash
# Via MCP
context({ action: 'scaffoldPlan', planName: 'my-feature', title: 'My Feature', summary: 'What it does' })

# Manual creation in .context/plans/my-feature.md
```

Structure each phase with concrete steps:

```markdown
## Phases

### P - Planning
- [ ] Define requirements and acceptance criteria
- [ ] Identify affected services and files
- [ ] Choose workflow scale

### R - Review (for MEDIUM/LARGE)
- [ ] Review architecture impact
- [ ] Document design decisions as ADRs
- [ ] Get plan approval

### E - Execution
- [ ] Implement service logic in src/services/<domain>/
- [ ] Add MCP gateway handler (if applicable)
- [ ] Update CLI integration (if applicable)
- [ ] Add i18n keys for new user-facing strings
- [ ] Update type exports

### V - Validation
- [ ] Write unit tests with jest.mock() for externals
- [ ] Run full test suite: npm test
- [ ] Manual CLI verification: npx tsx src/index.ts <command>
- [ ] TypeScript compilation check: npm run build

### C - Confirmation (for LARGE)
- [ ] Update CHANGELOG.md
- [ ] Update relevant .context/ documentation
- [ ] Update README if public API changed
```

### 5. Identify Dependencies and Risks

Common dependencies to flag:
- **AI provider changes**: Require testing with actual API keys (not just mocks)
- **tree-sitter changes**: Optional dependency -- test with and without it installed
- **MCP protocol changes**: Must maintain backward compatibility with existing clients
- **Frontmatter format changes**: Must handle both v1 and v2 formats
- **i18n additions**: Both locales must be updated simultaneously

### 6. Link the Plan to the Workflow

After creating the plan, link it to the active workflow:

```
plan({ action: 'link', planSlug: 'my-feature' })
```

This enables phase tracking and the `commitPhase` action for git integration.

## Example: Breaking Down "Add Caching to Semantic Analysis"

**Scale**: MEDIUM (multiple files, design decision on cache strategy)

**Tasks**:
1. P: Define cache invalidation strategy (file mtime vs. content hash)
2. P: Decide cache storage location (`.context/.cache/` vs. temp dir)
3. R: Review impact on `CodebaseAnalyzer` and `SemanticContextBuilder`
4. E: Add cache layer to `src/services/semantic/codebaseAnalyzer.ts`
5. E: Add cache config to `AnalyzerOptions` type
6. E: Wire cache option through MCP `context({ action: 'buildSemantic' })` params
7. V: Test cache hit/miss with `codebaseAnalyzer.test.ts`
8. V: Test that `cacheEnabled: false` bypasses cache
9. V: Manual test with large repo to verify performance improvement

**Files affected**: `src/services/semantic/codebaseAnalyzer.ts`, `src/services/semantic/types.ts`, `src/services/mcp/gateway/context.ts`, `src/services/mcp/mcpServer.ts`


================================================
FILE: .context/skills/pr-review/SKILL.md
================================================
---
type: skill
name: PR Review
description: Review pull requests against team standards and best practices
skillSlug: pr-review
phases: [R, V]
generated: 2026-03-18
status: filled
scaffoldVersion: "2.0.0"
---

# PR Review

Review pull requests for the `@dotcontext/cli` project against established patterns and quality standards.

## When to Use

- Reviewing a PR before merge
- Validating changes during the Review (R) or Validation (V) phases
- Checking that a PR meets the project's architectural and testing standards

## PR Review Process

### 1. Understand the Change Scope

Check which areas are affected:

```bash
# View changed files grouped by area
git diff main...HEAD --stat
```

Map changes to project layers:
- `src/services/mcp/` -- MCP server and gateway tools
- `src/services/<domain>/` -- Service layer business logic
- `src/generators/` -- Scaffold generation
- `src/workflow/` -- PREVC workflow system
- `src/utils/` -- Shared utilities
- `src/index.ts` -- CLI command definitions
- `.context/` -- Documentation and scaffolding content

### 2. Verify the Commit History

This project uses Conventional Commits:

```
<type>(<scope>): <description>
```

Check that:
- [ ] Each commit has a valid type (`feat`, `fix`, `refactor`, `docs`, `test`, `chore`)
- [ ] Scope matches the primary area of change (see commit-message skill for scope list)
- [ ] Messages are in imperative mood ("add", not "added")
- [ ] Breaking changes use `!` suffix and `BREAKING CHANGE:` footer

### 3. Architecture Review

#### Service Layer Compliance
- [ ] New services follow the directory-per-service pattern under `src/services/`
- [ ] Services export through `index.ts` barrel files
- [ ] Constructor accepts options object; async init is a separate method
- [ ] Dependencies are injectable (like `contextBuilder` in `AIContextMCPServer`)

#### MCP Tool Changes
- [ ] Zod schemas have `.describe()` on every parameter
- [ ] Gateway handler covers all actions in the enum (no unreachable branches)
- [ ] Responses use `createJsonResponse`/`createErrorResponse` from `response.ts`
- [ ] New types exported through `gatewayTools.ts` barrel
- [ ] Total MCP tool count remains manageable (currently 9)
- [ ] Tool description strings include all action names for AI discovery

#### Generator Changes
- [ ] Generators use v2 frontmatter (`scaffoldVersion: "2.0.0"`)
- [ ] `force` flag is respected (skip existing when false)
- [ ] Result type includes generated/skipped counts
- [ ] Templates are in `templates/` subdirectory

#### Workflow Changes
- [ ] Phase transitions follow PREVC order
- [ ] Scale-dependent phases are correctly skipped
- [ ] Gate logic is enforced unless explicitly bypassed

### 4. Code Quality Checks

- [ ] No `any` types; use `unknown` + type guards
- [ ] No `console.log` in MCP server code (use `process.stderr.write`)
- [ ] File paths use `path.join()`/`path.resolve()`, never string concatenation
- [ ] Optional dependencies (tree-sitter) handled with graceful fallback
- [ ] Error messages are user-friendly (CLI) or structured JSON (MCP)

### 5. Testing Verification

```bash
# Run all tests
npm test

# Build check
npm run build
```

- [ ] New services have `.test.ts` files
- [ ] Tests mock external dependencies (`jest.mock()` for AI providers, fs)
- [ ] Temp directories used (`fs.mkdtemp`) and cleaned up (`afterEach`)
- [ ] Mock `CLIInterface` and `TranslateFn` provided where needed
- [ ] MCP handler tests call handler functions directly (not through transport)

### 6. i18n Completeness

- [ ] New user-facing strings added to both `en` and `pt-BR` in `src/utils/i18n.ts`
- [ ] Translation keys use dot notation (`commands.new.description`)
- [ ] CLI output uses `t()` function, not hardcoded strings

### 7. Documentation Impact

- [ ] `CHANGELOG.md` updated if the change is user-facing
- [ ] `README.md` updated if public CLI commands or MCP tools changed
- [ ] `.context/docs/` updated if architecture changed significantly
- [ ] MCP tool description strings updated if actions added/removed

## Common PR Issues

### Missing Barrel Exports
New types or handlers added in `src/services/mcp/gateway/*.ts` but not re-exported through `gateway/index.ts` and `gatewayTools.ts`.

### Inconsistent Error Handling
MCP handlers that throw instead of returning `createErrorResponse()`. CLI commands that swallow errors silently.

### Untested Edge Cases
- What happens when `.context/` directory does not exist?
- What happens when tree-sitter is not installed?
- What happens with empty or malformed frontmatter?
- What happens with relative vs. absolute paths?

### Breaking MCP Compatibility
Renaming or removing an MCP tool action without a migration path. Always add new actions alongside old ones, then deprecate.

## PR Description Template

When creating PRs for this project:

```markdown
## Summary
- What this PR does (1-3 bullet points)

## Changes
- List of key changes by file/area

## Test plan
- [ ] Unit tests pass: `npm test`
- [ ] Build succeeds: `npm run build`
- [ ] Manual verification: `npx tsx src/index.ts <command>`
- [ ] MCP tool tested (if applicable)
```


================================================
FILE: .context/skills/refactoring/SKILL.md
================================================
---
type
Download .txt
gitextract__l45jdix/

├── .context/
│   ├── agents/
│   │   ├── README.md
│   │   ├── bug-fixer.md
│   │   ├── code-reviewer.md
│   │   ├── documentation-writer.md
│   │   ├── feature-developer.md
│   │   ├── performance-optimizer.md
│   │   ├── refactoring-specialist.md
│   │   └── test-writer.md
│   ├── docs/
│   │   ├── README.md
│   │   ├── codebase-map.json
│   │   ├── development-workflow.md
│   │   ├── harness-roadmap.md
│   │   ├── harness-split-foundation.md
│   │   ├── project-overview.md
│   │   ├── qa/
│   │   │   ├── README.md
│   │   │   ├── error-handling.md
│   │   │   ├── getting-started.md
│   │   │   └── project-structure.md
│   │   ├── testing-strategy.md
│   │   └── tooling.md
│   └── skills/
│       ├── README.md
│       ├── api-design/
│       │   └── SKILL.md
│       ├── bug-investigation/
│       │   └── SKILL.md
│       ├── code-review/
│       │   └── SKILL.md
│       ├── commit-message/
│       │   └── SKILL.md
│       ├── documentation/
│       │   └── SKILL.md
│       ├── feature-breakdown/
│       │   └── SKILL.md
│       ├── pr-review/
│       │   └── SKILL.md
│       ├── refactoring/
│       │   └── SKILL.md
│       ├── security-audit/
│       │   └── SKILL.md
│       └── test-generation/
│           └── SKILL.md
├── .env.example
├── .github/
│   ├── PULL_REQUEST_BODY.md
│   └── workflows/
│       ├── ci.yml
│       └── release.yml
├── .gitignore
├── .npmignore
├── AGENTS.md
├── ARCHITECTURE.md
├── CHANGELOG.md
├── CLAUDE.md
├── CONTRIBUTING.md
├── CONVENTIONS.md
├── LICENSE
├── README.md
├── docs/
│   ├── CONTEXT-WORKFLOW-HARNESS-CLI-PTBR.md
│   └── GUIDE.md
├── example-documentation.ts
├── jest.config.js
├── package.json
├── prompts/
│   ├── update_plan_prompt.md
│   └── update_scaffold_prompt.md
├── scripts/
│   ├── build-package-bundles.js
│   ├── release-packages.js
│   ├── smoke-package-bundles.js
│   └── test-mcp.js
├── src/
│   ├── cli/
│   │   ├── index.test.ts
│   │   └── index.ts
│   ├── cli.test.ts
│   ├── generators/
│   │   ├── agents/
│   │   │   ├── agentConfig.ts
│   │   │   ├── agentGenerator.test.ts
│   │   │   ├── agentGenerator.ts
│   │   │   ├── agentTypes.ts
│   │   │   ├── index.ts
│   │   │   └── templates/
│   │   │       ├── index.ts
│   │   │       ├── indexTemplate.ts
│   │   │       └── types.ts
│   │   ├── documentation/
│   │   │   ├── codebaseMapGenerator.ts
│   │   │   ├── documentationGenerator.test.ts
│   │   │   ├── documentationGenerator.ts
│   │   │   ├── guideRegistry.ts
│   │   │   ├── index.ts
│   │   │   └── templates/
│   │   │       ├── common.ts
│   │   │       ├── index.ts
│   │   │       ├── indexTemplate.ts
│   │   │       └── types.ts
│   │   ├── plans/
│   │   │   ├── index.ts
│   │   │   ├── planGenerator.test.ts
│   │   │   ├── planGenerator.ts
│   │   │   └── templates/
│   │   │       ├── indexTemplate.ts
│   │   │       ├── planTemplate.ts
│   │   │       └── types.ts
│   │   ├── shared/
│   │   │   ├── contextGenerator.ts
│   │   │   ├── directoryTemplateHelpers.ts
│   │   │   ├── generatorUtils.ts
│   │   │   ├── index.ts
│   │   │   ├── scaffoldStructures.ts
│   │   │   └── structures/
│   │   │       ├── agents/
│   │   │       │   ├── definitions.ts
│   │   │       │   ├── factory.ts
│   │   │       │   └── index.ts
│   │   │       ├── documentation/
│   │   │       │   ├── apiReference.ts
│   │   │       │   ├── architecture.ts
│   │   │       │   ├── dataFlow.ts
│   │   │       │   ├── glossary.ts
│   │   │       │   ├── index.ts
│   │   │       │   ├── migration.ts
│   │   │       │   ├── onboarding.ts
│   │   │       │   ├── projectOverview.ts
│   │   │       │   ├── security.ts
│   │   │       │   ├── testing.ts
│   │   │       │   ├── tooling.ts
│   │   │       │   ├── troubleshooting.ts
│   │   │       │   └── workflow.ts
│   │   │       ├── index.ts
│   │   │       ├── plans/
│   │   │       │   ├── index.ts
│   │   │       │   └── planStructure.ts
│   │   │       ├── registry.ts
│   │   │       ├── serialization.ts
│   │   │       ├── skills/
│   │   │       │   ├── definitions.ts
│   │   │       │   ├── factory.ts
│   │   │       │   └── index.ts
│   │   │       ├── types.ts
│   │   │       └── validation.ts
│   │   └── skills/
│   │       ├── index.ts
│   │       ├── skillGenerator.test.ts
│   │       ├── skillGenerator.ts
│   │       └── templates/
│   │           ├── indexTemplate.ts
│   │           └── skillTemplate.ts
│   ├── harness/
│   │   ├── index.test.ts
│   │   └── index.ts
│   ├── index.ts
│   ├── mcp/
│   │   ├── bin.test.ts
│   │   ├── bin.ts
│   │   ├── index.test.ts
│   │   └── index.ts
│   ├── prompts/
│   │   └── defaults.ts
│   ├── services/
│   │   ├── autoFill/
│   │   │   ├── autoFillService.ts
│   │   │   └── index.ts
│   │   ├── cli/
│   │   │   ├── index.ts
│   │   │   ├── mcpInstallService.test.ts
│   │   │   ├── mcpInstallService.ts
│   │   │   └── stateDetector.ts
│   │   ├── export/
│   │   │   ├── contextExportService.ts
│   │   │   ├── exportRulesService.ts
│   │   │   ├── index.ts
│   │   │   ├── skillExportService.test.ts
│   │   │   └── skillExportService.ts
│   │   ├── harness/
│   │   │   ├── agentsService.ts
│   │   │   ├── contextService.ts
│   │   │   ├── contextTools.test.ts
│   │   │   ├── contextTools.ts
│   │   │   ├── datasetService.test.ts
│   │   │   ├── datasetService.ts
│   │   │   ├── executionService.test.ts
│   │   │   ├── executionService.ts
│   │   │   ├── index.ts
│   │   │   ├── plansService.ts
│   │   │   ├── policyService.test.ts
│   │   │   ├── policyService.ts
│   │   │   ├── replayService.test.ts
│   │   │   ├── replayService.ts
│   │   │   ├── runtimeStateService.test.ts
│   │   │   ├── runtimeStateService.ts
│   │   │   ├── sensorCatalogService.ts
│   │   │   ├── sensorsService.test.ts
│   │   │   ├── sensorsService.ts
│   │   │   ├── skillsService.ts
│   │   │   ├── taskContractsService.test.ts
│   │   │   ├── taskContractsService.ts
│   │   │   └── workflowStateService.ts
│   │   ├── import/
│   │   │   ├── agentsDetector.ts
│   │   │   ├── importAgentsService.ts
│   │   │   ├── importRulesService.ts
│   │   │   ├── index.ts
│   │   │   ├── presets.ts
│   │   │   ├── rulesDetector.ts
│   │   │   └── types.ts
│   │   ├── mcp/
│   │   │   ├── README.md
│   │   │   ├── actionLogger.test.ts
│   │   │   ├── actionLogger.ts
│   │   │   ├── gateway/
│   │   │   │   ├── agent.ts
│   │   │   │   ├── context.test.ts
│   │   │   │   ├── context.ts
│   │   │   │   ├── explore.ts
│   │   │   │   ├── harness.test.ts
│   │   │   │   ├── harness.ts
│   │   │   │   ├── index.ts
│   │   │   │   ├── metrics.test.ts
│   │   │   │   ├── metrics.ts
│   │   │   │   ├── plan.ts
│   │   │   │   ├── response.ts
│   │   │   │   ├── shared.ts
│   │   │   │   ├── skill.ts
│   │   │   │   ├── sync.ts
│   │   │   │   ├── types.ts
│   │   │   │   ├── workflowAdvance.ts
│   │   │   │   ├── workflowInit.ts
│   │   │   │   ├── workflowManage.test.ts
│   │   │   │   ├── workflowManage.ts
│   │   │   │   ├── workflowStatus.test.ts
│   │   │   │   └── workflowStatus.ts
│   │   │   ├── gatewayTools.ts
│   │   │   ├── index.ts
│   │   │   ├── mcpInstallService.ts
│   │   │   ├── mcpServer.test.ts
│   │   │   └── mcpServer.ts
│   │   ├── qa/
│   │   │   ├── index.ts
│   │   │   ├── patternInferer.ts
│   │   │   ├── qaService.ts
│   │   │   └── topicDetector.ts
│   │   ├── quickSync/
│   │   │   ├── index.ts
│   │   │   └── quickSyncService.ts
│   │   ├── report/
│   │   │   ├── index.ts
│   │   │   └── reportService.ts
│   │   ├── reverseSync/
│   │   │   ├── importSkillsService.ts
│   │   │   ├── index.ts
│   │   │   ├── presets.ts
│   │   │   ├── reverseQuickSyncService.ts
│   │   │   ├── skillsDetector.ts
│   │   │   ├── toolDetector.ts
│   │   │   └── types.ts
│   │   ├── semantic/
│   │   │   ├── codebaseAnalyzer.test.ts
│   │   │   ├── codebaseAnalyzer.ts
│   │   │   ├── contextBuilder.ts
│   │   │   ├── contextCache.test.ts
│   │   │   ├── contextCache.ts
│   │   │   ├── index.ts
│   │   │   ├── lsp/
│   │   │   │   ├── index.ts
│   │   │   │   └── lspLayer.ts
│   │   │   ├── semanticSnapshotService.test.ts
│   │   │   ├── semanticSnapshotService.ts
│   │   │   ├── treeSitter/
│   │   │   │   ├── index.ts
│   │   │   │   └── treeSitterLayer.ts
│   │   │   └── types.ts
│   │   ├── shared/
│   │   │   ├── __tests__/
│   │   │   │   └── contextRootResolver.test.ts
│   │   │   ├── contentTypeRegistry.ts
│   │   │   ├── contextLayout.ts
│   │   │   ├── contextRootResolver.ts
│   │   │   ├── executionContext.ts
│   │   │   ├── globPatterns.ts
│   │   │   ├── index.ts
│   │   │   ├── pathHelpers.ts
│   │   │   ├── toolRegistry.ts
│   │   │   ├── types.ts
│   │   │   └── uiHelpers.ts
│   │   ├── stack/
│   │   │   ├── index.ts
│   │   │   ├── projectTypeClassifier.ts
│   │   │   ├── scaffoldFilter.ts
│   │   │   └── stackDetector.ts
│   │   ├── state/
│   │   │   ├── index.ts
│   │   │   ├── stateDetector.test.ts
│   │   │   └── stateDetector.ts
│   │   ├── sync/
│   │   │   ├── index.ts
│   │   │   ├── markdownReferenceHandler.ts
│   │   │   ├── presets.ts
│   │   │   ├── symlinkHandler.ts
│   │   │   ├── syncService.ts
│   │   │   └── types.ts
│   │   └── workflow/
│   │       ├── autoAdvance.ts
│   │       ├── index.ts
│   │       ├── workflowService.test.ts
│   │       └── workflowService.ts
│   ├── tests/
│   │   └── integrity/
│   │       └── postRefactoringIntegrity.test.ts
│   ├── types/
│   │   └── scaffoldFrontmatter.ts
│   ├── types.ts
│   ├── utils/
│   │   ├── cliUI.ts
│   │   ├── fileMapper.ts
│   │   ├── frontMatter.test.ts
│   │   ├── frontMatter.ts
│   │   ├── gitService.ts
│   │   ├── gitignoreManager.test.ts
│   │   ├── gitignoreManager.ts
│   │   ├── i18n.test.ts
│   │   ├── i18n.ts
│   │   ├── pathSecurity.test.ts
│   │   ├── pathSecurity.ts
│   │   ├── processShutdown.ts
│   │   ├── prompts/
│   │   │   ├── configSummary.ts
│   │   │   ├── index.ts
│   │   │   ├── smartDefaults.ts
│   │   │   └── types.ts
│   │   ├── splashScreen.test.ts
│   │   ├── splashScreen.ts
│   │   ├── theme.ts
│   │   ├── themedPrompt.ts
│   │   ├── versionChecker.test.ts
│   │   └── versionChecker.ts
│   ├── version.ts
│   └── workflow/
│       ├── agents/
│       │   ├── agentRegistry.ts
│       │   └── index.ts
│       ├── collaboration.ts
│       ├── errors.ts
│       ├── gates/
│       │   ├── gateChecker.test.ts
│       │   ├── gateChecker.ts
│       │   └── index.ts
│       ├── index.ts
│       ├── orchestration/
│       │   ├── agentOrchestrator.ts
│       │   ├── documentLinker.ts
│       │   └── index.ts
│       ├── orchestrator.ts
│       ├── phases.ts
│       ├── plans/
│       │   ├── index.ts
│       │   ├── planLinker.ts
│       │   └── types.ts
│       ├── prevcConfig.ts
│       ├── roles.ts
│       ├── scaling.ts
│       ├── skills/
│       │   ├── frontmatter.ts
│       │   ├── index.ts
│       │   ├── skillRegistry.ts
│       │   ├── skillTemplates.ts
│       │   └── types.ts
│       ├── status/
│       │   ├── statusManager.test.ts
│       │   ├── statusManager.ts
│       │   └── templates.ts
│       └── types.ts
├── templates/
│   └── packages/
│       ├── cli.README.md
│       ├── harness.README.md
│       └── mcp.README.md
└── tsconfig.json
Download .txt
SYMBOL INDEX (1901 symbols across 162 files)

FILE: example-documentation.ts
  function scaffoldRepo (line 11) | async function scaffoldRepo(repoRoot: string, outputDir: string = path.j...

FILE: scripts/build-package-bundles.js
  function ensureDir (line 10) | function ensureDir(dir) {
  function readJson (line 14) | function readJson(filePath) {
  function writeJson (line 18) | function writeJson(filePath, value) {
  function copyFile (line 22) | function copyFile(src, dest) {
  function copyDir (line 27) | function copyDir(src, dest) {
  function resetDir (line 41) | function resetDir(dir) {
  function writeExecutable (line 46) | function writeExecutable(filePath, content) {
  function createLocalBinShims (line 52) | function createLocalBinShims(pkgRoot, manifest) {
  function loadTemplate (line 73) | function loadTemplate(name) {
  function createManifest (line 77) | function createManifest(rootPkg, packageName, description, main, types, ...
  function packageDependencies (line 100) | function packageDependencies(rootPkg, names) {
  function buildBundles (line 110) | function buildBundles() {

FILE: scripts/release-packages.js
  function run (line 15) | function run(command, args) {
  function assert (line 22) | function assert(condition, message) {
  function resolveVersion (line 28) | function resolveVersion(input) {
  function copyDir (line 42) | function copyDir(src, dest) {
  function rewriteBundleVersion (line 55) | function rewriteBundleVersion(bundleDir, version) {
  function buildRelease (line 62) | function buildRelease(version) {
  function main (line 96) | function main() {

FILE: scripts/smoke-package-bundles.js
  function assert (line 54) | function assert(condition, message) {
  function requireFresh (line 60) | function requireFresh(filePath) {
  function runBundleCommand (line 66) | function runBundleCommand(bundleRoot, args) {
  function smokeBundle (line 74) | function smokeBundle(bundle) {
  function main (line 131) | function main() {

FILE: scripts/test-mcp.js
  function send (line 22) | function send(method, params = {}) {
  function runTests (line 43) | async function runTests() {
  function sleep (line 88) | function sleep(ms) {

FILE: src/generators/agents/agentConfig.ts
  constant AGENT_RESPONSIBILITIES (line 3) | const AGENT_RESPONSIBILITIES: Record<AgentType, string[]> = {
  constant AGENT_BEST_PRACTICES (line 96) | const AGENT_BEST_PRACTICES: Record<AgentType, string[]> = {

FILE: src/generators/agents/agentGenerator.test.ts
  function createRepoStructure (line 9) | function createRepoStructure(rootPath: string): RepoStructure {

FILE: src/generators/agents/agentGenerator.ts
  type AgentContext (line 19) | interface AgentContext {
  type AvailableSkill (line 25) | interface AvailableSkill {
  type AgentGenerationConfig (line 32) | interface AgentGenerationConfig {
  constant AGENT_SKILL_MAP (line 48) | const AGENT_SKILL_MAP: Partial<Record<AgentType, string[]>> = {
  constant AGENT_PHASES (line 61) | const AGENT_PHASES: Record<AgentType, PrevcPhase[]> = {
  function formatAgentTitle (line 81) | function formatAgentTitle(agentType: AgentType): string {
  class AgentGenerator (line 88) | class AgentGenerator {
    method constructor (line 102) | constructor(..._legacyArgs: unknown[]) {}
    method generateAgentPrompts (line 104) | async generateAgentPrompts(
    method renderSkillsSection (line 212) | private renderSkillsSection(agentType: AgentType, availableSkills: Ava...
    method getRelevantSymbolsForAgent (line 230) | private getRelevantSymbolsForAgent(agentType: AgentType, semantics?: S...
    method resolveAgentSelection (line 321) | private resolveAgentSelection(
    method buildContext (line 341) | private buildContext(repoStructure: RepoStructure, semantics?: Semanti...

FILE: src/generators/agents/agentTypes.ts
  constant AGENT_TYPES (line 1) | const AGENT_TYPES = [
  type AgentType (line 18) | type AgentType = typeof AGENT_TYPES[number];
  constant IMPORTANT_FILES (line 20) | const IMPORTANT_FILES = [

FILE: src/generators/agents/templates/indexTemplate.ts
  function renderAgentIndex (line 4) | function renderAgentIndex(agentTypes: readonly AgentType[]): string {
  function formatTitle (line 31) | function formatTitle(agentType: string): string {

FILE: src/generators/agents/templates/types.ts
  type DocTouchpoint (line 4) | interface DocTouchpoint {
  type KeySymbolInfo (line 9) | interface KeySymbolInfo {
  type AgentTemplateContext (line 16) | interface AgentTemplateContext {

FILE: src/generators/documentation/codebaseMapGenerator.ts
  type KeyFile (line 20) | interface KeyFile {
  type NavigationHints (line 26) | interface NavigationHints {
  type SemanticSnapshotMetadata (line 33) | interface SemanticSnapshotMetadata {
  type CodebaseMap (line 43) | interface CodebaseMap {
  type CodebaseMapOptions (line 109) | interface CodebaseMapOptions {
  function createEmptyFunctionalPatterns (line 114) | function createEmptyFunctionalPatterns(): DetectedFunctionalPatterns {
  constant DIRECTORY_DESCRIPTIONS (line 134) | const DIRECTORY_DESCRIPTIONS: Record<string, string> = {
  constant KEY_FILE_PATTERNS (line 189) | const KEY_FILE_PATTERNS: Array<{ pattern: RegExp; description: string; c...
  class CodebaseMapGenerator (line 208) | class CodebaseMapGenerator {
    method constructor (line 212) | constructor(options: CodebaseMapOptions = {}) {
    method generate (line 217) | generate(
    method buildStackSection (line 241) | private buildStackSection(stackInfo?: StackInfo, repoRoot?: string): C...
    method buildStructureSection (line 312) | private buildStructureSection(repoStructure: RepoStructure): CodebaseM...
    method getDirectoryDescription (line 350) | private getDirectoryDescription(dirName: string): string {
    method buildArchitectureSection (line 372) | private buildArchitectureSection(
    method categorizeEntryPoints (line 415) | private categorizeEntryPoints(entryPoints: string[]): {
    method buildDependenciesSection (line 458) | private buildDependenciesSection(repoRoot: string, semantics?: Semanti...
    method inferFileDescription (line 481) | private inferFileDescription(filePath: string): string | undefined {
    method buildStatsSection (line 521) | private buildStatsSection(repoStructure: RepoStructure, semantics?: Se...
    method relativePath (line 549) | private relativePath(repoRoot: string, filePath: string): string {
    method buildKeyFilesSection (line 556) | private buildKeyFilesSection(repoStructure: RepoStructure, semantics?:...
    method enhanceFileDescription (line 608) | private enhanceFileDescription(
    method inferCategory (line 638) | private inferCategory(filePath: string): KeyFile['category'] {
    method buildNavigationSection (line 655) | private buildNavigationSection(repoStructure: RepoStructure, stackInfo...

FILE: src/generators/documentation/documentationGenerator.test.ts
  function createRepoStructure (line 9) | function createRepoStructure(rootPath: string): RepoStructure {

FILE: src/generators/documentation/documentationGenerator.ts
  constant DOC_CATEGORY_MAP (line 25) | const DOC_CATEGORY_MAP: Record<string, DocScaffoldFrontmatter['category'...
  function getDocInfo (line 39) | function getDocInfo(key: string): { title: string; description: string; ...
  type DocumentationGenerationConfig (line 51) | interface DocumentationGenerationConfig {
  class DocumentationGenerator (line 62) | class DocumentationGenerator {
    method constructor (line 65) | constructor(..._legacyArgs: unknown[]) {}
    method generateDocumentation (line 67) | async generateDocumentation(
    method buildContext (line 183) | private buildContext(
    method deriveTopLevelDirectories (line 213) | private deriveTopLevelDirectories(repoStructure: RepoStructure): strin...
    method updateAgentGuideReferences (line 224) | private async updateAgentGuideReferences(repoStructure: RepoStructure,...
    method createDefaultAgentGuide (line 256) | private createDefaultAgentGuide(repoStructure: RepoStructure): string {

FILE: src/generators/documentation/guideRegistry.ts
  constant DOCUMENT_GUIDES (line 3) | const DOCUMENT_GUIDES: GuideMeta[] = [
  constant DOCUMENT_GUIDE_KEYS (line 54) | const DOCUMENT_GUIDE_KEYS = DOCUMENT_GUIDES.map(guide => guide.key);
  function getGuidesByKeys (line 56) | function getGuidesByKeys(keys?: string[]): GuideMeta[] {
  function getDocFilesByKeys (line 66) | function getDocFilesByKeys(keys?: string[]): Set<string> | undefined {

FILE: src/generators/documentation/templates/common.ts
  function wrapWithFrontMatter (line 9) | function wrapWithFrontMatter(
  constant KNOWN_DESCRIPTIONS (line 24) | const KNOWN_DESCRIPTIONS: Record<string, string> = {
  function formatDirectoryList (line 33) | function formatDirectoryList(
  function buildDocumentMapTable (line 57) | function buildDocumentMapTable(guides: DocumentationTemplateContext['gui...
  function formatDirectoryStats (line 62) | function formatDirectoryStats(stats: DirectoryStat[]): string {
  function formatInlineDirectoryList (line 72) | function formatInlineDirectoryList(directories: string[]): string {
  function formatSymbolRef (line 86) | function formatSymbolRef(
  function formatCodeLocation (line 98) | function formatCodeLocation(
  function formatFileRef (line 111) | function formatFileRef(
  function buildSymbolTable (line 125) | function buildSymbolTable(
  function buildSymbolList (line 168) | function buildSymbolList(
  function groupSymbolsByDirectory (line 188) | function groupSymbolsByDirectory(

FILE: src/generators/documentation/templates/indexTemplate.ts
  function renderIndex (line 4) | function renderIndex(context: DocumentationTemplateContext): string {

FILE: src/generators/documentation/templates/types.ts
  type GuideMeta (line 4) | interface GuideMeta {
  type DirectoryStat (line 11) | interface DirectoryStat {
  type DocumentationTemplateContext (line 16) | interface DocumentationTemplateContext {

FILE: src/generators/plans/planGenerator.test.ts
  function createTempOutput (line 7) | function createTempOutput(prefix: string): Promise<string> {

FILE: src/generators/plans/planGenerator.ts
  type PlanGeneratorOptions (line 13) | interface PlanGeneratorOptions {
  type PlanGenerationResult (line 26) | interface PlanGenerationResult {
  class PlanGenerator (line 32) | class PlanGenerator {
    method generatePlan (line 35) | async generatePlan(options: PlanGeneratorOptions): Promise<PlanGenerat...
    method resolveAgents (line 118) | private resolveAgents(selected?: string[] | null): PlanAgentSummary[] {
    method buildCodebaseSnapshot (line 137) | private buildCodebaseSnapshot(semantics: SemanticContext): CodebaseSna...
    method updatePlanIndex (line 149) | private async updatePlanIndex(plansDir: string, verbose: boolean): Pro...

FILE: src/generators/plans/templates/indexTemplate.ts
  function renderPlanIndex (line 3) | function renderPlanIndex(entries: PlanIndexEntry[]): string {

FILE: src/generators/plans/templates/planTemplate.ts
  function wrapWithPlanFrontMatter (line 19) | function wrapWithPlanFrontMatter(
  function renderCodebaseSnapshot (line 58) | function renderCodebaseSnapshot(snapshot?: CodebaseSnapshot): string {
  function renderKeyComponents (line 83) | function renderKeyComponents(semantics?: SemanticContext): string {
  function renderPlanTemplate (line 115) | function renderPlanTemplate(context: PlanTemplateContext): string {

FILE: src/generators/plans/templates/types.ts
  type PlanAgentSummary (line 5) | interface PlanAgentSummary {
  type CodebaseSnapshot (line 11) | interface CodebaseSnapshot {
  type PlanTemplateContext (line 19) | interface PlanTemplateContext {
  type PlanIndexEntry (line 29) | interface PlanIndexEntry {

FILE: src/generators/shared/contextGenerator.ts
  class ContextGenerator (line 3) | class ContextGenerator {
    method constructor (line 4) | constructor(protected readonly fileMapper: FileMapper) {}
    method loadFileContent (line 6) | protected async loadFileContent(path: string): Promise<string> {

FILE: src/generators/shared/directoryTemplateHelpers.ts
  function formatDirectoryList (line 1) | function formatDirectoryList(directories: string[], placeholderMessage?:...

FILE: src/generators/shared/generatorUtils.ts
  class GeneratorUtils (line 6) | class GeneratorUtils {
    method formatBytes (line 7) | static formatBytes(bytes: number): string {
    method slugify (line 15) | static slugify(text: string): string {
    method formatModuleName (line 22) | static formatModuleName(name: string): string {
    method formatTitle (line 29) | static formatTitle(text: string): string {
    method ensureDirectoryAndLog (line 35) | static async ensureDirectoryAndLog(dir: string, verbose: boolean, desc...
    method writeFileWithLogging (line 42) | static async writeFileWithLogging(
    method logError (line 61) | static logError(message: string, error: any, verbose: boolean): void {
    method logProgress (line 67) | static logProgress(message: string, verbose: boolean): void {
    method getFileTypeDistribution (line 73) | static getFileTypeDistribution(repoStructure: RepoStructure): Map<stri...
    method getTopFileExtensions (line 82) | static getTopFileExtensions(repoStructure: RepoStructure, limit: numbe...
    method createTimestamp (line 89) | static createTimestamp(): string {
    method createGeneratedByFooter (line 93) | static createGeneratedByFooter(additionalInfo?: string): string {

FILE: src/generators/shared/structures/agents/factory.ts
  type AgentDefaultContent (line 10) | interface AgentDefaultContent {
  constant SECTION_KEY_MAP (line 27) | const SECTION_KEY_MAP: Record<string, keyof AgentDefaultContent> = {
  function createAgentStructure (line 44) | function createAgentStructure(

FILE: src/generators/shared/structures/documentation/architecture.ts
  constant SEMANTIC_SNAPSHOT_GUIDANCE (line 3) | const SEMANTIC_SNAPSHOT_GUIDANCE =

FILE: src/generators/shared/structures/documentation/projectOverview.ts
  constant SEMANTIC_SNAPSHOT_GUIDANCE (line 3) | const SEMANTIC_SNAPSHOT_GUIDANCE =

FILE: src/generators/shared/structures/registry.ts
  constant SCAFFOLD_STRUCTURES (line 15) | const SCAFFOLD_STRUCTURES: Record<string, ScaffoldStructure> = {
  function getScaffoldStructure (line 65) | function getScaffoldStructure(name: string): ScaffoldStructure | undefin...
  function getStructuresByType (line 72) | function getStructuresByType(fileType: ScaffoldFileType): ScaffoldStruct...

FILE: src/generators/shared/structures/serialization.ts
  function serializeStructureAsMarkdown (line 12) | function serializeStructureAsMarkdown(structure: ScaffoldStructure): str...
  function formatSectionAsMarkdown (line 40) | function formatSectionAsMarkdown(section: ScaffoldSection): string {
  function getPlaceholderForContentType (line 72) | function getPlaceholderForContentType(contentType: string, required: boo...
  function serializeStructureForAI (line 96) | function serializeStructureForAI(structure: ScaffoldStructure): string {

FILE: src/generators/shared/structures/skills/factory.ts
  type SkillDefaultContent (line 10) | interface SkillDefaultContent {
  constant SECTION_KEY_MAP (line 20) | const SECTION_KEY_MAP: Record<string, keyof SkillDefaultContent> = {
  constant RESOURCE_STRATEGY_DEFAULT (line 26) | const RESOURCE_STRATEGY_DEFAULT = `- Add \`scripts/\` only when the task...
  function createSkillStructure (line 34) | function createSkillStructure(

FILE: src/generators/shared/structures/types.ts
  type ScaffoldContentType (line 10) | type ScaffoldContentType =
  type ScaffoldTone (line 21) | type ScaffoldTone =
  type ScaffoldAudience (line 30) | type ScaffoldAudience =
  type ScaffoldSection (line 39) | interface ScaffoldSection {
  type ScaffoldStructure (line 61) | interface ScaffoldStructure {

FILE: src/generators/shared/structures/validation.ts
  function validateStructure (line 11) | function validateStructure(structure: ScaffoldStructure): string[] {
  function validateAllStructures (line 46) | function validateAllStructures(): Map<string, string[]> {

FILE: src/generators/skills/skillGenerator.ts
  type SkillGeneratorOptions (line 30) | interface SkillGeneratorOptions {
  type SkillGeneratorResult (line 41) | interface SkillGeneratorResult {
  class SkillGenerator (line 48) | class SkillGenerator {
    method constructor (line 53) | constructor(options: SkillGeneratorOptions) {
    method generate (line 62) | async generate(options: {
    method formatSkillTitle (line 132) | private formatSkillTitle(skillName: string): string {
    method buildSkillBody (line 139) | private buildSkillBody(skillName: string): string {
    method generateCustomSkill (line 184) | async generateCustomSkill(options: {
    method generateIndex (line 223) | async generateIndex(): Promise<string> {
  function createSkillGenerator (line 243) | function createSkillGenerator(options: SkillGeneratorOptions): SkillGene...

FILE: src/generators/skills/templates/indexTemplate.ts
  type SkillsIndexOptions (line 7) | interface SkillsIndexOptions {
  function generateSkillsIndex (line 15) | function generateSkillsIndex(options: SkillsIndexOptions): string {

FILE: src/generators/skills/templates/skillTemplate.ts
  type SkillTemplateOptions (line 18) | interface SkillTemplateOptions {
  function generateSkillContent (line 29) | function generateSkillContent(options: SkillTemplateOptions): string {
  function buildFrontmatter (line 45) | function buildFrontmatter(options: SkillTemplateOptions): string {
  function buildBody (line 68) | function buildBody(name: string, description: string): string {
  function getDefaultPhases (line 109) | function getDefaultPhases(skillName: string): PrevcPhase[] {

FILE: src/index.ts
  function scheduleVersionCheck (line 106) | function scheduleVersionCheck(force: boolean = false): Promise<void> {
  function registerSyncCommand (line 124) | function registerSyncCommand(parent: Command, name: string, hidden = fal...
  function registerPreviewSplashCommand (line 300) | function registerPreviewSplashCommand(parent: Command, hidden = false): ...
  function registerExportRulesCommand (line 317) | function registerExportRulesCommand(parent: Command, hidden = false): Co...
  function registerReportCommand (line 352) | function registerReportCommand(parent: Command, hidden = false): Command {
  function registerSkillCommands (line 385) | function registerSkillCommands(parent: Command, hidden = false): Command {
  function registerWorkflowCommands (line 479) | function registerWorkflowCommands(parent: Command, hidden = false): Comm...
  function selectLocale (line 654) | async function selectLocale(): Promise<void> {
  type InteractiveAction (line 669) | type InteractiveAction = 'syncAgents' | 'update' | 'changeLanguage' | 'e...
  type StateAction (line 670) | type StateAction = 'exit' | 'mcpInstall' | 'reverseSync' | 'settings';
  function runInteractive (line 672) | async function runInteractive(): Promise<void> {
  function runFullMenu (line 763) | async function runFullMenu(): Promise<void> {
  function displayPendingFiles (line 819) | async function displayPendingFiles(contextDir: string): Promise<void> {
  function runMcpInstall (line 832) | async function runMcpInstall(): Promise<void> {
  function runInteractiveSync (line 854) | async function runInteractiveSync(): Promise<void> {
  function runQuickSync (line 936) | async function runQuickSync(): Promise<void> {
  function runReverseSync (line 1081) | async function runReverseSync(): Promise<void> {
  function runSettings (line 1185) | async function runSettings(): Promise<void> {
  function renderStartupSplash (line 1190) | async function renderStartupSplash(
  function filterOutLocaleArgs (line 1208) | function filterOutLocaleArgs(args: string[]): string[] {
  function main (line 1224) | async function main(): Promise<void> {
  function isUserInterrupt (line 1239) | function isUserInterrupt(error: unknown): boolean {
  function handleGracefulExit (line 1253) | function handleGracefulExit(): void {

FILE: src/mcp/bin.ts
  type ParsedArgs (line 17) | type ParsedArgs = {
  function parseMcpPackageArgs (line 61) | function parseMcpPackageArgs(argv: string[]): ParsedArgs {
  function parseServeArgs (line 84) | function parseServeArgs(args: string[]): ParsedArgs {
  function parseInstallArgs (line 105) | function parseInstallArgs(args: string[]): ParsedArgs {
  function printHelp (line 152) | function printHelp(): void {
  function runInstallCommand (line 167) | async function runInstallCommand(args: ParsedArgs, argv: string[]): Prom...
  function runServeCommand (line 209) | async function runServeCommand(args: ParsedArgs): Promise<void> {
  function runMcpPackage (line 225) | async function runMcpPackage(argv: string[]): Promise<void> {

FILE: src/prompts/defaults.ts
  constant UPDATE_SCAFFOLD_PROMPT_FALLBACK (line 1) | const UPDATE_SCAFFOLD_PROMPT_FALLBACK = `# Prompt: Update Repository Doc...
  constant MCP_SCAFFOLD_ENHANCEMENT_PROMPT (line 34) | const MCP_SCAFFOLD_ENHANCEMENT_PROMPT = `# AI Enhancement Required
  constant UPDATE_PLAN_PROMPT_FALLBACK (line 74) | const UPDATE_PLAN_PROMPT_FALLBACK = `# Prompt: Update Collaboration Plans

FILE: src/services/autoFill/autoFillService.ts
  type AutoFillContext (line 14) | interface AutoFillContext {
  type DirectoryStat (line 21) | interface DirectoryStat {
  constant SEMANTIC_SNAPSHOT_REFERENCE (line 26) | const SEMANTIC_SNAPSHOT_REFERENCE =
  class AutoFillService (line 29) | class AutoFillService {
    method fillDocumentation (line 33) | fillDocumentation(
    method fillAgent (line 60) | fillAgent(
    method fillSection (line 75) | private fillSection(
    method fillAgentSection (line 85) | private fillAgentSection(
    method generateDocContent (line 95) | private generateDocContent(
    method generateAgentContent (line 117) | private generateAgentContent(
    method fillProjectOverviewSection (line 147) | private fillProjectOverviewSection(section: ScaffoldSection, ctx: Auto...
    method fillArchitectureSection (line 185) | private fillArchitectureSection(section: ScaffoldSection, ctx: AutoFil...
    method fillToolingSection (line 211) | private fillToolingSection(section: ScaffoldSection, ctx: AutoFillCont...
    method generateProjectOverview (line 231) | private generateProjectOverview(ctx: AutoFillContext): string {
    method generateQuickFacts (line 249) | private generateQuickFacts(ctx: AutoFillContext): string {
    method formatEntryPoints (line 275) | private formatEntryPoints(entryPoints: string[]): string {
    method formatPublicAPI (line 283) | private formatPublicAPI(symbols: ExtractedSymbol[]): string {
    method formatPublicAPITable (line 297) | private formatPublicAPITable(symbols: ExtractedSymbol[]): string {
    method formatDirectoryStructure (line 315) | private formatDirectoryStructure(directories: string[]): string {
    method formatTechStack (line 326) | private formatTechStack(stackInfo?: StackInfo): string {
    method formatFrameworks (line 356) | private formatFrameworks(stackInfo?: StackInfo): string {
    method formatBuildTools (line 364) | private formatBuildTools(stackInfo?: StackInfo): string {
    method formatTestFrameworks (line 372) | private formatTestFrameworks(stackInfo?: StackInfo): string {
    method formatPackageManager (line 380) | private formatPackageManager(stackInfo?: StackInfo): string {
    method formatLayers (line 388) | private formatLayers(layers: ArchitectureLayer[]): string {
    method formatPatterns (line 403) | private formatPatterns(patterns: DetectedPattern[]): string {
    method generateGettingStarted (line 422) | private generateGettingStarted(stackInfo?: StackInfo): string {
    method generateKeyFilesForAgent (line 467) | private generateKeyFilesForAgent(agentType: string, ctx: AutoFillConte...
    method generateRelevantSymbolsForAgent (line 496) | private generateRelevantSymbolsForAgent(agentType: string, ctx: AutoFi...
    method getFilePatternForAgent (line 515) | private getFilePatternForAgent(agentType: string): RegExp[] {
    method getRelevantSymbolsForAgent (line 547) | private getRelevantSymbolsForAgent(agentType: string, semantics: Seman...

FILE: src/services/cli/mcpInstallService.ts
  type MCPInstallServiceDependencies (line 25) | type MCPInstallServiceDependencies = BaseDependencies;
  type MCPInstallOptions (line 27) | interface MCPInstallOptions {
  type MCPInstallResult (line 40) | interface MCPInstallResult extends OperationResult {
  type MCPInstallation (line 44) | interface MCPInstallation {
  type MCPInstallToolChoice (line 52) | interface MCPInstallToolChoice {
  type MCPInstallToolPrompt (line 57) | interface MCPInstallToolPrompt {
  type ResolveMcpInstallToolSelectionOptions (line 62) | interface ResolveMcpInstallToolSelectionOptions {
  type MCPServerConfig (line 74) | interface MCPServerConfig {
  type MCPConfigTemplate (line 80) | interface MCPConfigTemplate {
  constant AI_CONTEXT_MCP_SERVER (line 98) | const AI_CONTEXT_MCP_SERVER: MCPServerConfig = {
  function buildCodexTomlConfig (line 107) | function buildCodexTomlConfig(existingConfig: string, server: MCPServerC...
  constant MCP_CONFIG_TEMPLATES (line 129) | const MCP_CONFIG_TEMPLATES: MCPConfigTemplate[] = [
  class MCPInstallService (line 499) | class MCPInstallService {
    method constructor (line 500) | constructor(private deps: MCPInstallServiceDependencies) {}
    method getSupportedTools (line 505) | getSupportedTools(): ToolDefinition[] {
    method getSupportedToolIds (line 512) | getSupportedToolIds(): string[] {
    method detectInstalledTools (line 519) | async detectInstalledTools(): Promise<string[]> {
    method run (line 540) | async run(options: MCPInstallOptions = {}): Promise<MCPInstallResult> {
    method installForTool (line 607) | private async installForTool(
  function buildMcpInstallToolChoices (line 719) | function buildMcpInstallToolChoices(
  function resolveMcpInstallToolSelection (line 744) | async function resolveMcpInstallToolSelection(

FILE: src/services/cli/stateDetector.ts
  type ProjectState (line 18) | type ProjectState = 'new' | 'unfilled' | 'ready' | 'outdated';
  type StateDetectionResult (line 20) | interface StateDetectionResult {
  type StateDetectorOptions (line 34) | interface StateDetectorOptions {
  constant DEFAULT_SOURCE_DIRS (line 40) | const DEFAULT_SOURCE_DIRS = ['src', 'lib', 'app', 'packages'];
  class StateDetector (line 42) | class StateDetector {
    method constructor (line 47) | constructor(options: StateDetectorOptions) {
    method contextDir (line 53) | get contextDir(): string {
    method detect (line 60) | async detect(): Promise<StateDetectionResult> {
    method getNewestMtime (line 133) | private async getNewestMtime(dirs: string[]): Promise<Date | undefined> {
    method getContextMtime (line 165) | private async getContextMtime(): Promise<Date | undefined> {
    method describeState (line 187) | static describeState(result: StateDetectionResult): string {

FILE: src/services/export/contextExportService.ts
  type ContextExportServiceDependencies (line 19) | type ContextExportServiceDependencies = BaseDependencies;
  type ContextExportOptions (line 21) | interface ContextExportOptions {
  type ContextExportResult (line 44) | interface ContextExportResult extends OperationResult {
  class ContextExportService (line 51) | class ContextExportService {
    method constructor (line 52) | constructor(private deps: ContextExportServiceDependencies) {}
    method run (line 57) | async run(repoPath: string, options: ContextExportOptions = {}): Promi...

FILE: src/services/export/exportRulesService.ts
  type ExportRulesServiceDependencies (line 24) | type ExportRulesServiceDependencies = BaseDependencies;
  type ExportTarget (line 26) | interface ExportTarget {
  type ExportOptions (line 35) | interface ExportOptions {
  type ExportResult (line 46) | interface ExportResult extends OperationResult {
  type RuleFile (line 50) | interface RuleFile {
  function buildExportPresets (line 59) | function buildExportPresets(): Record<string, ExportTarget[]> {
  function deduplicateTargets (line 91) | function deduplicateTargets(targets: ExportTarget[]): ExportTarget[] {
  constant EXPORT_PRESETS (line 108) | const EXPORT_PRESETS: Record<string, ExportTarget[]> = buildExportPreset...
  class ExportRulesService (line 110) | class ExportRulesService {
    method constructor (line 111) | constructor(private deps: ExportRulesServiceDependencies) {}
    method run (line 116) | async run(repoPath: string, options: ExportOptions = {}): Promise<Expo...
    method exportToTarget (line 167) | private async exportToTarget(
    method resolveTargets (line 236) | private resolveTargets(options: ExportOptions): ExportTarget[] {
    method readSourceRules (line 277) | private async readSourceRules(sourcePath: string, indexMode?: 'readme'...
    method readReadmeIndexFiles (line 323) | private async readReadmeIndexFiles(sourcePath: string): Promise<RuleFi...
    method combineRules (line 356) | private combineRules(rules: RuleFile[]): string {
    method exportToDirectory (line 374) | private async exportToDirectory(
    method getAvailablePresets (line 390) | getAvailablePresets(): string[] {

FILE: src/services/export/skillExportService.ts
  type SkillExportServiceDependencies (line 21) | type SkillExportServiceDependencies = BaseDependencies;
  type SkillExportTarget (line 23) | interface SkillExportTarget {
  type SkillExportOptions (line 29) | interface SkillExportOptions {
  type SkillExportResult (line 41) | interface SkillExportResult extends OperationResult {
  function buildSkillExportPresets (line 49) | function buildSkillExportPresets(): Record<string, SkillExportTarget[]> {
  constant SKILL_EXPORT_PRESETS (line 68) | const SKILL_EXPORT_PRESETS: Record<string, SkillExportTarget[]> = buildS...
  class SkillExportService (line 70) | class SkillExportService {
    method constructor (line 71) | constructor(private deps: SkillExportServiceDependencies) {}
    method run (line 76) | async run(repoPath: string, options: SkillExportOptions = {}): Promise...
    method getSkillsToExport (line 124) | private async getSkillsToExport(repoPath: string, options: SkillExport...
    method exportToTarget (line 174) | private async exportToTarget(
    method exportSkill (line 214) | private async exportSkill(
    method generateSkillContent (line 258) | private generateSkillContent(skill: Skill): string {
    method resolveTargets (line 273) | private resolveTargets(options: SkillExportOptions): SkillExportTarget...
    method getAvailablePresets (line 307) | getAvailablePresets(): string[] {

FILE: src/services/harness/agentsService.ts
  type HarnessAgentsServiceOptions (line 18) | interface HarnessAgentsServiceOptions {
  class HarnessAgentsService (line 22) | class HarnessAgentsService {
    method constructor (line 23) | constructor(private readonly options: HarnessAgentsServiceOptions) {}
    method repoPath (line 25) | private get repoPath(): string {
    method discover (line 29) | async discover(): Promise<Record<string, unknown>> {
    method getInfo (line 48) | async getInfo(agentType: string): Promise<Record<string, unknown>> {
    method orchestrate (line 58) | orchestrate(params: {
    method getSequence (line 90) | getSequence(params: {
    method getDocs (line 118) | getDocs(agent: AgentType): Record<string, unknown> {
    method getPhaseDocs (line 137) | getPhaseDocs(phase: PrevcPhase): Record<string, unknown> {
    method listTypes (line 157) | listTypes(): Record<string, unknown> {

FILE: src/services/harness/contextService.ts
  type HarnessContextServiceOptions (line 28) | interface HarnessContextServiceOptions {
  type HarnessContextInitResult (line 33) | interface HarnessContextInitResult {
  type HarnessContextPlanScaffoldResult (line 44) | interface HarnessContextPlanScaffoldResult {
  type HarnessBootstrapStatusResult (line 55) | interface HarnessBootstrapStatusResult {
  class HarnessContextService (line 94) | class HarnessContextService {
    method constructor (line 95) | constructor(private readonly options: HarnessContextServiceOptions) {}
    method repoPath (line 97) | private get repoPath(): string {
    method check (line 101) | async check(repoPath?: string): Promise<unknown> {
    method bootstrapStatus (line 108) | async bootstrapStatus(repoPath?: string): Promise<HarnessBootstrapStat...
    method init (line 202) | async init(params: {
    method fill (line 277) | async fill(params: {
    method fillSingle (line 296) | async fillSingle(params: { repoPath?: string; filePath: string }): Pro...
    method listToFill (line 303) | async listToFill(params: {
    method getMap (line 318) | async getMap(params: { repoPath?: string; section?: string }): Promise...
    method buildSemantic (line 328) | async buildSemantic(params: {
    method scaffoldPlan (line 366) | async scaffoldPlan(params: {
    method searchQA (line 417) | async searchQA(params: {
    method generateQA (line 440) | async generateQA(params: {
    method getFlow (line 464) | async getFlow(params: {
    method detectPatterns (line 495) | async detectPatterns(params: {
  function buildPlanWorkflowPrompt (line 531) | function buildPlanWorkflowPrompt(params: {
  function buildPlanWorkflowNextSteps (line 559) | function buildPlanWorkflowNextSteps(params: {

FILE: src/services/harness/contextTools.ts
  type ToolContext (line 31) | type ToolContext = unknown;
  type InternalTool (line 33) | interface InternalTool<TInput, TOutput> {
  function createInternalTool (line 38) | function createInternalTool<TInput, TOutput>(
  type ScaffoldTarget (line 45) | type ScaffoldTarget = 'docs' | 'agents' | 'skills' | 'plans' | 'sensors'...
  type ScaffoldFileType (line 46) | type ScaffoldFileType = 'doc' | 'agent' | 'skill' | 'plan' | 'sensor';
  type ScaffoldFileInfo (line 48) | interface ScaffoldFileInfo {
  type RequiredAction (line 55) | interface RequiredAction {
  function collectScaffoldFiles (line 64) | async function collectScaffoldFiles(
  function resolveScaffoldFileInfo (line 155) | function resolveScaffoldFileInfo(outputDir: string, filePath: string): S...
  function getDocFillInstructions (line 205) | function getDocFillInstructions(fileName: string): string {
  function getAgentFillInstructions (line 209) | function getAgentFillInstructions(agentType: string): string {
  function getSkillFillInstructions (line 213) | function getSkillFillInstructions(skillSlug: string): string {
  function getSensorFillInstructions (line 217) | function getSensorFillInstructions(): string {
  function sensorCatalogNeedsFill (line 221) | async function sensorCatalogNeedsFill(filePath: string): Promise<boolean> {
  function hasContent (line 230) | async function hasContent(dirPath: string): Promise<boolean> {
  function hasSkillContent (line 239) | async function hasSkillContent(skillsDir: string): Promise<boolean> {
  function hasHarnessRuntimeContent (line 256) | async function hasHarnessRuntimeContent(harnessDir: string): Promise<boo...
  function getTreeSitterLayer (line 268) | function getTreeSitterLayer(): TreeSitterLayer {
  function getOrBuildContext (line 278) | async function getOrBuildContext(repoPath: string): Promise<string> {
  function cleanupSharedContext (line 309) | async function cleanupSharedContext(): Promise<void> {
  constant TOOL_NAMES (line 1183) | const TOOL_NAMES = [
  type ToolName (line 1198) | type ToolName = (typeof TOOL_NAMES)[number];

FILE: src/services/harness/datasetService.ts
  type HarnessFailureKind (line 10) | type HarnessFailureKind = 'sensor' | 'task' | 'session' | 'trace';
  type HarnessFailureRecord (line 12) | interface HarnessFailureRecord {
  type HarnessFailureCluster (line 24) | interface HarnessFailureCluster {
  type HarnessFailureDataset (line 33) | interface HarnessFailureDataset {
  type HarnessDatasetServiceOptions (line 45) | interface HarnessDatasetServiceOptions {
  type BuildHarnessDatasetOptions (line 50) | interface BuildHarnessDatasetOptions {
  type HarnessDatasetDependencies (line 55) | interface HarnessDatasetDependencies {
  function nowIso (line 61) | function nowIso(): string {
  function normalizeSignature (line 65) | function normalizeSignature(value: string): string {
  function buildSensorFailures (line 73) | function buildSensorFailures(replay: HarnessReplayRecord): HarnessFailur...
  function buildTaskFailures (line 93) | async function buildTaskFailures(
  function buildSessionFailure (line 126) | function buildSessionFailure(replay: HarnessReplayRecord): HarnessFailur...
  function buildTraceFailures (line 150) | function buildTraceFailures(replay: HarnessReplayRecord): HarnessFailure...
  function clusterFailures (line 170) | function clusterFailures(failures: HarnessFailureRecord[]): HarnessFailu...
  class HarnessDatasetService (line 205) | class HarnessDatasetService {
    method constructor (line 210) | constructor(private readonly options: HarnessDatasetServiceOptions) {
    method repoPath (line 236) | private get repoPath(): string {
    method datasetsPath (line 240) | private get datasetsPath(): string {
    method datasetFile (line 244) | private datasetFile(datasetId: string): string {
    method ensureLayout (line 248) | private async ensureLayout(): Promise<void> {
    method buildFailureDataset (line 252) | async buildFailureDataset(options: BuildHarnessDatasetOptions = {}): P...
    method listDatasets (line 289) | async listDatasets(): Promise<HarnessFailureDataset[]> {
    method getDataset (line 301) | async getDataset(datasetId: string): Promise<HarnessFailureDataset> {
    method getFailureClusters (line 310) | async getFailureClusters(datasetId: string): Promise<HarnessFailureClu...

FILE: src/services/harness/executionService.ts
  type HarnessExecutionServiceOptions (line 36) | interface HarnessExecutionServiceOptions {
  type HarnessSessionQualitySnapshot (line 40) | interface HarnessSessionQualitySnapshot {
  class HarnessExecutionService (line 47) | class HarnessExecutionService {
    method constructor (line 55) | constructor(private readonly options: HarnessExecutionServiceOptions) {
    method createSession (line 81) | createSession(input: CreateSessionInput) {
    method listSessions (line 85) | listSessions() {
    method getSession (line 89) | getSession(sessionId: string) {
    method appendTrace (line 93) | appendTrace(sessionId: string, input: AppendTraceInput) {
    method listTraces (line 97) | listTraces(sessionId: string) {
    method addArtifact (line 101) | async addArtifact(sessionId: string, input: AddArtifactInput) {
    method listArtifacts (line 112) | listArtifacts(sessionId: string) {
    method checkpointSession (line 116) | async checkpointSession(sessionId: string, input: CheckpointInput = {}) {
    method resumeSession (line 126) | resumeSession(sessionId: string) {
    method completeSession (line 130) | async completeSession(sessionId: string, note?: string) {
    method failSession (line 140) | async failSession(sessionId: string, message: string) {
    method runSensor (line 150) | async runSensor(
    method getSessionSensorRuns (line 170) | getSessionSensorRuns(sessionId: string) {
    method createTaskContract (line 174) | async createTaskContract(input: Parameters<HarnessTaskContractsService...
    method listTaskContracts (line 184) | listTaskContracts() {
    method evaluateTaskCompletion (line 188) | evaluateTaskCompletion(taskId: string, sessionId?: string): Promise<Ha...
    method createHandoffContract (line 192) | async createHandoffContract(input: Parameters<HarnessTaskContractsServ...
    method listHandoffContracts (line 202) | listHandoffContracts() {
    method listPolicies (line 206) | listPolicies(): Promise<HarnessPolicyRule[]> {
    method registerPolicy (line 210) | registerPolicy(input: {
    method getPolicy (line 235) | getPolicy(): Promise<HarnessPolicyDocument> {
    method setPolicy (line 239) | setPolicy(input: {
    method resetPolicy (line 251) | async resetPolicy(): Promise<HarnessPolicyDocument> {
    method evaluatePolicy (line 255) | evaluatePolicy(input: HarnessPolicyEvaluationInput): Promise<HarnessPo...
    method replaySession (line 259) | replaySession(sessionId: string): Promise<HarnessReplayRecord> {
    method listReplays (line 263) | listReplays(sessionId?: string): Promise<HarnessReplayRecord[]> {
    method exportFailureDataset (line 267) | exportFailureDataset(sessionIds?: string[]): Promise<HarnessFailureDat...
    method listDatasets (line 274) | listDatasets(): Promise<HarnessFailureDataset[]> {
    method getDataset (line 278) | getDataset(datasetId: string): Promise<HarnessFailureDataset> {
    method getFailureClusters (line 282) | getFailureClusters(datasetId: string): Promise<HarnessFailureCluster[]> {
    method getSessionQuality (line 286) | async getSessionQuality(

FILE: src/services/harness/plansService.ts
  type HarnessPlansServiceOptions (line 17) | interface HarnessPlansServiceOptions {
  class HarnessPlansService (line 21) | class HarnessPlansService {
    method constructor (line 24) | constructor(private readonly options: HarnessPlansServiceOptions) {
    method repoPath (line 30) | private get repoPath(): string {
    method link (line 34) | async link(planSlug: string): Promise<Record<string, unknown>> {
    method getLinked (line 99) | async getLinked(): Promise<Record<string, unknown>> {
    method getDetails (line 104) | async getDetails(planSlug: string): Promise<Record<string, unknown>> {
    method getForPhase (line 126) | async getForPhase(phase: PrevcPhase): Promise<Record<string, unknown>> {
    method updatePhase (line 144) | async updatePhase(planSlug: string, phaseId: string, status: 'pending'...
    method recordDecision (line 149) | async recordDecision(params: {
    method updateStep (line 167) | async updateStep(params: {
    method getStatus (line 192) | async getStatus(planSlug: string): Promise<Record<string, unknown>> {
    method syncMarkdown (line 205) | async syncMarkdown(planSlug: string): Promise<Record<string, unknown>> {
    method commitPhase (line 215) | async commitPhase(params: {

FILE: src/services/harness/policyService.ts
  type HarnessPolicyEffect (line 5) | type HarnessPolicyEffect = 'allow' | 'deny' | 'require_approval';
  type HarnessPolicyRisk (line 6) | type HarnessPolicyRisk = 'low' | 'medium' | 'high' | 'critical';
  type HarnessPolicyTarget (line 7) | type HarnessPolicyTarget = 'tool' | 'action' | 'path' | 'risk';
  type HarnessPolicyScope (line 8) | type HarnessPolicyScope = HarnessPolicyTarget;
  type HarnessPolicyDefaultEffect (line 9) | type HarnessPolicyDefaultEffect = 'allow' | 'deny';
  type HarnessPolicyRuleSelector (line 11) | interface HarnessPolicyRuleSelector {
  type HarnessPolicyRule (line 18) | interface HarnessPolicyRule {
  type HarnessPolicyDocument (line 28) | interface HarnessPolicyDocument {
  type HarnessPolicyApproval (line 34) | interface HarnessPolicyApproval {
  type HarnessPolicyEvaluationInput (line 39) | interface HarnessPolicyEvaluationInput {
  type HarnessPolicyLegacyEnforcementInput (line 50) | interface HarnessPolicyLegacyEnforcementInput {
  type HarnessPolicyMatch (line 60) | interface HarnessPolicyMatch {
  type HarnessPolicyDecision (line 67) | interface HarnessPolicyDecision {
  type HarnessPolicyEvaluationResult (line 76) | type HarnessPolicyEvaluationResult = HarnessPolicyDecision;
  type CreateHarnessPolicyRuleInput (line 78) | interface CreateHarnessPolicyRuleInput {
  type HarnessPolicyServiceOptions (line 87) | interface HarnessPolicyServiceOptions {
  type CreateHarnessBootstrapPolicyOptions (line 91) | interface CreateHarnessBootstrapPolicyOptions {
  class HarnessPolicyBlockedError (line 95) | class HarnessPolicyBlockedError extends Error {
    method constructor (line 96) | constructor(
  function normalizePath (line 105) | function normalizePath(input: string): string {
  function escapeRegex (line 109) | function escapeRegex(input: string): string {
  function globToRegExp (line 113) | function globToRegExp(pattern: string): RegExp {
  function matchesAnyPattern (line 127) | function matchesAnyPattern(value: string, patterns: string[]): boolean {
  function riskRank (line 139) | function riskRank(risk: HarnessPolicyRisk): number {
  function compareRisk (line 148) | function compareRisk(inputRisk: HarnessPolicyRisk | undefined, ruleRisk:...
  function normalizeRule (line 158) | function normalizeRule(rule: HarnessPolicyRule): HarnessPolicyRule {
  function isLegacyEnforcementInput (line 180) | function isLegacyEnforcementInput(
  constant CORE_DIRECTORY_CANDIDATES (line 186) | const CORE_DIRECTORY_CANDIDATES = [
  constant ROOT_CONFIG_FILE_CANDIDATES (line 207) | const ROOT_CONFIG_FILE_CANDIDATES = [
  constant ROOT_SOURCE_FILE_EXTENSIONS (line 234) | const ROOT_SOURCE_FILE_EXTENSIONS = new Set([
  constant CONFIG_DIRECTORY_PATTERNS (line 252) | const CONFIG_DIRECTORY_PATTERNS: Array<{ path: string; pattern: string }...
  class HarnessPolicyService (line 266) | class HarnessPolicyService {
    method constructor (line 267) | constructor(private readonly options: HarnessPolicyServiceOptions) {}
    method repoPath (line 269) | private get repoPath(): string {
    method policyPath (line 273) | private get policyPath(): string {
    method toEvaluationInput (line 277) | private toEvaluationInput(
    method loadPolicy (line 295) | async loadPolicy(): Promise<HarnessPolicyDocument> {
    method savePolicy (line 312) | async savePolicy(policy: HarnessPolicyDocument): Promise<HarnessPolicy...
    method listRules (line 323) | async listRules(): Promise<HarnessPolicyRule[]> {
    method evaluateWithPolicy (line 328) | private evaluateWithPolicy(input: HarnessPolicyEvaluationInput, policy...
    method evaluate (line 397) | async evaluate(input: HarnessPolicyEvaluationInput, policy?: HarnessPo...
    method evaluateAndAuthorize (line 402) | async evaluateAndAuthorize(
    method authorize (line 410) | async authorize(
    method enforce (line 430) | async enforce(
    method setPolicyFromRules (line 437) | async setPolicyFromRules(input: {
    method setPolicy (line 448) | async setPolicy(policy: HarnessPolicyDocument): Promise<HarnessPolicyD...
    method setPolicyDocument (line 456) | async setPolicyDocument(policy: HarnessPolicyDocument): Promise<Harnes...
    method registerRule (line 460) | async registerRule(input: CreateHarnessPolicyRuleInput): Promise<Harne...
    method evaluateLegacy (line 476) | async evaluateLegacy(input: HarnessPolicyEvaluationInput): Promise<Har...
    method assertAllowed (line 480) | async assertAllowed(input: HarnessPolicyEvaluationInput): Promise<void> {
    method evaluatePolicy (line 495) | async evaluatePolicy(input: HarnessPolicyEvaluationInput): Promise<Har...
    method evaluateRule (line 499) | async evaluateRule(input: HarnessPolicyEvaluationInput): Promise<Harne...
    method getPolicy (line 503) | async getPolicy(): Promise<HarnessPolicyDocument> {
    method detectStackInfo (line 507) | private async detectStackInfo(): Promise<StackInfo | undefined> {
    method readTopLevelEntries (line 515) | private async readTopLevelEntries(): Promise<{ files: string[]; direct...
    method getCorePathPatterns (line 543) | private getCorePathPatterns(topLevelEntries: { files: string[]; direct...
    method getConfigPathPatterns (line 558) | private async getConfigPathPatterns(topLevelEntries: { files: string[]...
    method buildCoreRuleReason (line 582) | private buildCoreRuleReason(stackInfo?: StackInfo): string {
    method createBootstrapPolicy (line 596) | async createBootstrapPolicy(

FILE: src/services/harness/replayService.ts
  type HarnessReplayEventSource (line 20) | type HarnessReplayEventSource =
  type HarnessReplayEvent (line 29) | interface HarnessReplayEvent {
  type HarnessReplayRecord (line 38) | interface HarnessReplayRecord {
  type HarnessReplayServiceOptions (line 57) | interface HarnessReplayServiceOptions {
  type ReplaySessionOptions (line 62) | interface ReplaySessionOptions {
  type HarnessReplayDependencies (line 67) | interface HarnessReplayDependencies {
  function nowIso (line 73) | function nowIso(): string {
  function sortByCreatedAt (line 77) | function sortByCreatedAt<T extends { createdAt: string }>(items: T[]): T...
  class HarnessReplayService (line 81) | class HarnessReplayService {
    method constructor (line 86) | constructor(private readonly options: HarnessReplayServiceOptions) {
    method repoPath (line 102) | private get repoPath(): string {
    method replaysPath (line 106) | private get replaysPath(): string {
    method replayFile (line 110) | private replayFile(replayId: string): string {
    method ensureLayout (line 114) | private async ensureLayout(): Promise<void> {
    method saveReplay (line 118) | private async saveReplay(replay: HarnessReplayRecord): Promise<void> {
    method readReplay (line 123) | private async readReplay(replayId: string): Promise<HarnessReplayRecor...
    method buildReplay (line 132) | async buildReplay(
    method replaySession (line 273) | async replaySession(
    method listReplays (line 282) | async listReplays(filter?: { sessionId?: string }): Promise<HarnessRep...
    method getReplay (line 298) | async getReplay(replayId: string): Promise<HarnessReplayRecord> {

FILE: src/services/harness/runtimeStateService.ts
  type HarnessSessionStatus (line 12) | type HarnessSessionStatus = 'active' | 'paused' | 'completed' | 'failed';
  type HarnessTraceLevel (line 13) | type HarnessTraceLevel = 'debug' | 'info' | 'warn' | 'error';
  type HarnessArtifactKind (line 14) | type HarnessArtifactKind = 'text' | 'json' | 'file';
  type HarnessRuntimeStateServiceOptions (line 16) | interface HarnessRuntimeStateServiceOptions {
  type HarnessSessionCheckpoint (line 20) | interface HarnessSessionCheckpoint {
  type HarnessSessionRecord (line 28) | interface HarnessSessionRecord {
  type HarnessTraceRecord (line 47) | interface HarnessTraceRecord {
  type HarnessArtifactRecord (line 57) | interface HarnessArtifactRecord {
  type HarnessRuntimeStatePort (line 68) | interface HarnessRuntimeStatePort {
  type CreateSessionInput (line 79) | interface CreateSessionInput {
  type AppendTraceInput (line 84) | interface AppendTraceInput {
  type AddArtifactInput (line 91) | interface AddArtifactInput {
  type CheckpointInput (line 99) | interface CheckpointInput {
  function nowIso (line 106) | function nowIso(): string {
  function normalizeContent (line 110) | function normalizeContent(content: unknown): unknown {
  class HarnessRuntimeStateService (line 122) | class HarnessRuntimeStateService {
    method constructor (line 123) | constructor(private readonly options: HarnessRuntimeStateServiceOption...
    method repoPath (line 125) | private get repoPath(): string {
    method contextPath (line 129) | private get contextPath(): string {
    method harnessPath (line 133) | private get harnessPath(): string {
    method sessionsPath (line 137) | private get sessionsPath(): string {
    method tracesPath (line 141) | private get tracesPath(): string {
    method artifactsPath (line 145) | private get artifactsPath(): string {
    method sessionFile (line 149) | private sessionFile(sessionId: string): string {
    method traceFile (line 153) | private traceFile(sessionId: string): string {
    method artifactFile (line 157) | private artifactFile(sessionId: string, artifactId: string): string {
    method ensureLayout (line 161) | private async ensureLayout(): Promise<void> {
    method readSession (line 167) | private async readSession(sessionId: string): Promise<HarnessSessionRe...
    method saveSession (line 176) | private async saveSession(session: HarnessSessionRecord): Promise<void> {
    method appendTraceLine (line 181) | private async appendTraceLine(sessionId: string, trace: HarnessTraceRe...
    method recordTrace (line 186) | private async recordTrace(sessionId: string, trace: HarnessTraceRecord...
    method createSession (line 198) | async createSession(input: CreateSessionInput): Promise<HarnessSession...
    method listSessions (line 229) | async listSessions(): Promise<HarnessSessionRecord[]> {
    method getSession (line 241) | async getSession(sessionId: string): Promise<HarnessSessionRecord> {
    method appendTrace (line 245) | async appendTrace(sessionId: string, input: AppendTraceInput): Promise...
    method addArtifact (line 260) | async addArtifact(sessionId: string, input: AddArtifactInput): Promise...
    method listCheckpoints (line 297) | async listCheckpoints(sessionId: string): Promise<HarnessSessionCheckp...
    method listArtifacts (line 302) | async listArtifacts(sessionId: string): Promise<HarnessArtifactRecord[...
    method listTraces (line 318) | async listTraces(sessionId: string): Promise<HarnessTraceRecord[]> {
    method checkpointSession (line 332) | async checkpointSession(sessionId: string, input: CheckpointInput = {}...
    method resumeSession (line 367) | async resumeSession(sessionId: string): Promise<HarnessSessionRecord> {
    method completeSession (line 390) | async completeSession(sessionId: string, note?: string): Promise<Harne...
    method failSession (line 408) | async failSession(sessionId: string, message: string): Promise<Harness...

FILE: src/services/harness/sensorCatalogService.ts
  type HarnessSensorCatalogSeverity (line 12) | type HarnessSensorCatalogSeverity = 'critical' | 'warning' | 'info';
  type HarnessShellSensorConfig (line 14) | interface HarnessShellSensorConfig {
  type HarnessSensorCatalogDocument (line 25) | interface HarnessSensorCatalogDocument {
  type HarnessSensorCatalogServiceOptions (line 40) | interface HarnessSensorCatalogServiceOptions {
  class HarnessSensorCatalogService (line 45) | class HarnessSensorCatalogService {
    method constructor (line 46) | constructor(private readonly options: HarnessSensorCatalogServiceOptio...
    method repoPath (line 48) | private get repoPath(): string {
    method contextPath (line 52) | private get contextPath(): string {
    method configPath (line 58) | get configPath(): string {
    method bootstrap (line 62) | async bootstrap(force: boolean = false): Promise<HarnessSensorCatalogD...
    method load (line 82) | async load(): Promise<HarnessSensorCatalogDocument | null> {
    method loadSync (line 90) | loadSync(): HarnessSensorCatalogDocument | null {
    method resolveEffectiveSensorsSync (line 98) | resolveEffectiveSensorsSync(): HarnessShellSensorConfig[] {
    method detectSensorsSync (line 109) | detectSensorsSync(): HarnessShellSensorConfig[] {
    method detectNodeSensors (line 261) | private detectNodeSensors(packageJsonPath: string): HarnessShellSensor...
    method serializeStack (line 323) | private serializeStack(stack: StackInfo): HarnessSensorCatalogDocument...

FILE: src/services/harness/sensorsService.ts
  type HarnessSensorSeverity (line 15) | type HarnessSensorSeverity = 'info' | 'warning' | 'critical';
  type HarnessSensorStatus (line 16) | type HarnessSensorStatus = 'passed' | 'failed' | 'skipped' | 'blocked';
  type HarnessSensorExecutionInput (line 18) | interface HarnessSensorExecutionInput {
  type HarnessSensorExecutionResult (line 25) | interface HarnessSensorExecutionResult {
  type HarnessSensorDefinition (line 33) | interface HarnessSensorDefinition {
  type HarnessSensorRun (line 42) | interface HarnessSensorRun extends HarnessSensorExecutionResult {
  type HarnessBackpressurePolicy (line 53) | interface HarnessBackpressurePolicy {
  type HarnessBackpressureResult (line 58) | interface HarnessBackpressureResult {
  type HarnessSensorsServiceOptions (line 64) | interface HarnessSensorsServiceOptions {
  class HarnessSensorsService (line 68) | class HarnessSensorsService {
    method constructor (line 71) | constructor(private readonly options: HarnessSensorsServiceOptions) {}
    method registerSensor (line 73) | registerSensor(definition: HarnessSensorDefinition): HarnessSensorDefi...
    method listSensors (line 78) | listSensors(): HarnessSensorDefinition[] {
    method getSensor (line 82) | getSensor(sensorId: string): HarnessSensorDefinition | undefined {
    method runSensor (line 86) | async runSensor(
    method getSessionSensorRuns (line 125) | async getSessionSensorRuns(sessionId: string): Promise<HarnessSensorRu...
    method evaluateBackpressure (line 132) | evaluateBackpressure(

FILE: src/services/harness/skillsService.ts
  type HarnessSkillsServiceOptions (line 15) | interface HarnessSkillsServiceOptions {
  function getSkillFillInstructions (line 19) | function getSkillFillInstructions(skillSlug: string): string {
  function buildSkillFillPrompt (line 87) | function buildSkillFillPrompt(
  class HarnessSkillsService (line 141) | class HarnessSkillsService {
    method constructor (line 142) | constructor(private readonly options: HarnessSkillsServiceOptions) {}
    method repoPath (line 144) | private get repoPath(): string {
    method getRegistry (line 148) | private getRegistry() {
    method list (line 153) | async list(includeContent?: boolean): Promise<Record<string, unknown>> {
    method getContent (line 179) | async getContent(skillSlug: string): Promise<Record<string, unknown>> {
    method getForPhase (line 206) | async getForPhase(phase: PrevcPhase): Promise<Record<string, unknown>> {
    method scaffold (line 225) | async scaffold(params: {
    method export (line 242) | async export(params: {
    method fill (line 268) | async fill(params: {

FILE: src/services/harness/taskContractsService.ts
  type HarnessTaskContractStatus (line 18) | type HarnessTaskContractStatus =
  type HarnessTaskContract (line 26) | interface HarnessTaskContract {
  type HarnessHandoffContract (line 43) | interface HarnessHandoffContract {
  type HarnessTaskCompletionResult (line 55) | interface HarnessTaskCompletionResult {
  type HarnessTaskContractsServiceOptions (line 66) | interface HarnessTaskContractsServiceOptions {
  class HarnessTaskContractsService (line 71) | class HarnessTaskContractsService {
    method constructor (line 72) | constructor(private readonly options: HarnessTaskContractsServiceOptio...
    method contractsPath (line 74) | private get contractsPath(): string {
    method tasksPath (line 78) | private get tasksPath(): string {
    method handoffsPath (line 82) | private get handoffsPath(): string {
    method ensureLayout (line 86) | private async ensureLayout(): Promise<void> {
    method taskFile (line 93) | private async taskFile(taskId: string): Promise<string> {
    method handoffFile (line 98) | private async handoffFile(handoffId: string): Promise<string> {
    method createTaskContract (line 103) | async createTaskContract(input: {
    method listTaskContracts (line 148) | async listTaskContracts(): Promise<HarnessTaskContract[]> {
    method getTaskContract (line 160) | async getTaskContract(taskId: string): Promise<HarnessTaskContract | n...
    method updateTaskContract (line 169) | async updateTaskContract(
    method createHandoffContract (line 188) | async createHandoffContract(input: {
    method listHandoffContracts (line 223) | async listHandoffContracts(): Promise<HarnessHandoffContract[]> {
    method evaluateTaskCompletion (line 235) | async evaluateTaskCompletion(taskId: string, sessionId?: string): Prom...

FILE: src/services/harness/workflowStateService.ts
  type HarnessWorkflowStateServiceOptions (line 13) | interface HarnessWorkflowStateServiceOptions {
  type WorkflowHarnessBinding (line 17) | interface WorkflowHarnessBinding {
  type HarnessWorkflowRecord (line 25) | interface HarnessWorkflowRecord {
  class HarnessWorkflowStateService (line 33) | class HarnessWorkflowStateService {
    method constructor (line 34) | constructor(private readonly options: HarnessWorkflowStateServiceOptio...
    method contextPath (line 36) | private get contextPath(): string {
    method workflowsPath (line 40) | private get workflowsPath(): string {
    method currentPath (line 44) | private get currentPath(): string {
    method archivePath (line 48) | private get archivePath(): string {
    method legacyBindingPath (line 52) | private get legacyBindingPath(): string {
    method ensureLayout (line 56) | private async ensureLayout(): Promise<void> {
    method normalizeBinding (line 60) | private normalizeBinding(value: unknown): WorkflowHarnessBinding | null {
    method normalizeRecord (line 90) | private normalizeRecord(
    method readLegacyBinding (line 110) | private async readLegacyBinding(): Promise<WorkflowHarnessBinding | nu...
    method readLegacyBindingSync (line 123) | private readLegacyBindingSync(): WorkflowHarnessBinding | null {
    method writeRecord (line 136) | private async writeRecord(record: HarnessWorkflowRecord): Promise<void> {
    method exists (line 144) | async exists(): Promise<boolean> {
    method loadRecord (line 148) | async loadRecord(): Promise<HarnessWorkflowRecord> {
    method load (line 164) | async load(): Promise<PrevcStatus> {
    method loadRecordSync (line 169) | loadRecordSync(): HarnessWorkflowRecord {
    method loadSync (line 175) | loadSync(): PrevcStatus {
    method save (line 180) | async save(status: PrevcStatus): Promise<void> {
    method getBinding (line 194) | async getBinding(): Promise<WorkflowHarnessBinding | null> {
    method saveBinding (line 202) | async saveBinding(binding: WorkflowHarnessBinding | null): Promise<voi...
    method remove (line 213) | async remove(): Promise<void> {
    method archive (line 222) | async archive(name: string): Promise<void> {

FILE: src/services/import/agentsDetector.ts
  function normalizeAgentFilename (line 7) | function normalizeAgentFilename(filePath: string): string {
  function normalizeAgentName (line 11) | function normalizeAgentName(filePath: string): string {
  class AgentsDetector (line 15) | class AgentsDetector {
    method detectAgents (line 19) | async detectAgents(repoPath: string, autoDetect: boolean = true): Prom...
    method detectFromPaths (line 108) | async detectFromPaths(sourcePaths: string[], repoPath: string): Promis...

FILE: src/services/import/importAgentsService.ts
  class ImportAgentsService (line 16) | class ImportAgentsService {
    method constructor (line 22) | constructor(dependencies: ImportServiceDependencies) {
    method run (line 29) | async run(rawOptions: ImportAgentsCommandFlags, repoPath: string = pro...
    method resolveOptions (line 82) | private async resolveOptions(
    method importFiles (line 103) | private async importFiles(
    method displayConfig (line 175) | private displayConfig(options: ImportAgentsOptions): void {
    method displaySummary (line 194) | private displaySummary(result: ImportResult, dryRun: boolean): void {

FILE: src/services/import/importRulesService.ts
  class ImportRulesService (line 17) | class ImportRulesService {
    method constructor (line 23) | constructor(dependencies: ImportServiceDependencies) {
    method run (line 30) | async run(rawOptions: ImportRulesCommandFlags, repoPath: string = proc...
    method resolveOptions (line 83) | private async resolveOptions(
    method importFiles (line 106) | private async importFiles(
    method formatContent (line 181) | private formatContent(content: string, file: RuleFileInfo, format: Imp...
    method formatAsMarkdown (line 193) | private formatAsMarkdown(content: string, file: RuleFileInfo): string {
    method formatAsFormatted (line 202) | private formatAsFormatted(content: string, file: RuleFileInfo): string {
    method displayConfig (line 207) | private displayConfig(options: ImportRulesOptions): void {
    method displaySummary (line 227) | private displaySummary(result: ImportResult, dryRun: boolean): void {

FILE: src/services/import/presets.ts
  function buildRuleSources (line 15) | function buildRuleSources(): RuleSource[] {
  function buildAgentSources (line 32) | function buildAgentSources(): RuleSource[] {
  constant RULE_SOURCES (line 39) | const RULE_SOURCES: RuleSource[] = buildRuleSources();
  constant AGENT_SOURCES (line 44) | const AGENT_SOURCES: RuleSource[] = buildAgentSources();
  function getRuleSourceByName (line 46) | function getRuleSourceByName(name: string): RuleSource | undefined {
  function getAgentSourceByName (line 50) | function getAgentSourceByName(name: string): RuleSource | undefined {
  function getAllRuleSourceNames (line 54) | function getAllRuleSourceNames(): string[] {
  function getAllAgentSourceNames (line 58) | function getAllAgentSourceNames(): string[] {

FILE: src/services/import/rulesDetector.ts
  class RulesDetector (line 7) | class RulesDetector {
    method detectRules (line 11) | async detectRules(repoPath: string, autoDetect: boolean = true): Promi...
    method detectFromPaths (line 107) | async detectFromPaths(sourcePaths: string[], repoPath: string): Promis...
    method findFilesInDirectory (line 168) | private async findFilesInDirectory(dirPath: string, patterns: string[]...
    method determineRuleType (line 187) | private determineRuleType(sourceName: string): RuleType {
    method determineRuleTypeFromPath (line 203) | private determineRuleTypeFromPath(filePath: string): RuleType {
    method generateTargetFilename (line 220) | private generateTargetFilename(sourcePath: string, type: RuleType): st...

FILE: src/services/import/types.ts
  type RuleType (line 4) | type RuleType =
  type ImportFormat (line 19) | type ImportFormat = 'markdown' | 'raw' | 'formatted';
  type RuleFileInfo (line 21) | interface RuleFileInfo {
  type ImportRulesCommandFlags (line 30) | interface ImportRulesCommandFlags {
  type ImportAgentsCommandFlags (line 40) | interface ImportAgentsCommandFlags {
  type ImportServiceDependencies (line 49) | interface ImportServiceDependencies {
  type ImportRulesOptions (line 55) | interface ImportRulesOptions {
  type ImportAgentsOptions (line 65) | interface ImportAgentsOptions {
  type ImportResult (line 74) | interface ImportResult {
  type DetectionResult (line 82) | interface DetectionResult {
  type RuleSource (line 87) | interface RuleSource {

FILE: src/services/mcp/actionLogger.ts
  type ActionStatus (line 14) | type ActionStatus = 'success' | 'error';
  type MCPActionLogEntry (line 16) | interface MCPActionLogEntry {
  constant SENSITIVE_KEYS (line 25) | const SENSITIVE_KEYS = new Set([
  constant MAX_DEPTH (line 37) | const MAX_DEPTH = 4;
  constant MAX_ARRAY (line 38) | const MAX_ARRAY = 20;
  constant MAX_STRING (line 39) | const MAX_STRING = 200;
  constant MCP_ACTIVITY_NAME (line 40) | const MCP_ACTIVITY_NAME = 'mcp-activity';
  function resolveContextPath (line 44) | async function resolveContextPath(repoPath: string): Promise<string> {
  function sanitizeValue (line 52) | function sanitizeValue(value: unknown, depth: number = 0): unknown {
  function sanitizeDetails (line 88) | function sanitizeDetails(details?: Record<string, unknown>): Record<stri...
  function resolveWorkflowSessionId (line 93) | async function resolveWorkflowSessionId(contextPath: string): Promise<st...
  function resolveMcpActivitySessionId (line 107) | async function resolveMcpActivitySessionId(
  function logMcpAction (line 142) | async function logMcpAction(

FILE: src/services/mcp/gateway/agent.ts
  type AgentOptions (line 18) | interface AgentOptions {
  function handleAgent (line 25) | async function handleAgent(

FILE: src/services/mcp/gateway/context.test.ts
  function parseResponse (line 8) | function parseResponse(response: { content: Array<{ text: string }> }) {

FILE: src/services/mcp/gateway/context.ts
  type ContextOptions (line 18) | interface ContextOptions {
  function handleContext (line 26) | async function handleContext(

FILE: src/services/mcp/gateway/explore.ts
  type ExploreOptions (line 21) | interface ExploreOptions {
  function handleExplore (line 28) | async function handleExplore(

FILE: src/services/mcp/gateway/harness.ts
  type HarnessOptions (line 13) | interface HarnessOptions {
  function normalizePolicyEffect (line 17) | function normalizePolicyEffect(effect?: string): HarnessPolicyEffect {
  function normalizePolicyTarget (line 29) | function normalizePolicyTarget(target?: string, pathPattern?: string, ri...
  function handleHarness (line 45) | async function handleHarness(

FILE: src/services/mcp/gateway/metrics.ts
  type SessionMetrics (line 11) | interface SessionMetrics {
  type MetricsSummary (line 26) | interface MetricsSummary {
  class MetricsStore (line 38) | class MetricsStore {
    method constructor (line 41) | constructor() {
    method createNewSession (line 45) | private createNewSession(): SessionMetrics {
    method recordContextQuery (line 59) | recordContextQuery(type: 'qa' | 'flow' | 'pattern' | 'other'): void {
    method recordFileRead (line 76) | recordFileRead(estimatedTokens: number = 1000): void {
    method getMetrics (line 82) | getMetrics(): SessionMetrics {
    method getSummary (line 86) | getSummary(): MetricsSummary {
    method reset (line 136) | reset(): void {
  function recordContextQuery (line 147) | function recordContextQuery(type: 'qa' | 'flow' | 'pattern' | 'other'): ...
  function recordFileRead (line 154) | function recordFileRead(estimatedTokens?: number): void {
  function getMetrics (line 161) | function getMetrics(): SessionMetrics {
  function getMetricsSummary (line 168) | function getMetricsSummary(): MetricsSummary {
  function resetMetrics (line 175) | function resetMetrics(): void {
  function handleMetricsAction (line 182) | function handleMetricsAction(action: 'get' | 'summary' | 'reset'): object {

FILE: src/services/mcp/gateway/plan.ts
  type PlanOptions (line 16) | interface PlanOptions {
  function handlePlan (line 23) | async function handlePlan(

FILE: src/services/mcp/gateway/response.ts
  type MCPToolResponse (line 11) | interface MCPToolResponse {
  function createJsonResponse (line 27) | function createJsonResponse(data: unknown): MCPToolResponse {
  function createErrorResponse (line 39) | function createErrorResponse(error: unknown): MCPToolResponse {
  function createTextResponse (line 55) | function createTextResponse(text: string): MCPToolResponse {
  function createScaffoldResponse (line 68) | function createScaffoldResponse(
  function buildEnhancementPrompt (line 123) | function buildEnhancementPrompt(pendingFiles: string[], repoPath?: strin...

FILE: src/services/mcp/gateway/skill.ts
  type SkillOptions (line 15) | interface SkillOptions {
  function handleSkill (line 22) | async function handleSkill(

FILE: src/services/mcp/gateway/sync.ts
  type SyncOptions (line 21) | interface SyncOptions {
  function handleSync (line 28) | async function handleSync(

FILE: src/services/mcp/gateway/types.ts
  type ExploreAction (line 16) | type ExploreAction = 'read' | 'list' | 'analyze' | 'search' | 'getStruct...
  type ContextAction (line 17) | type ContextAction = 'check' | 'bootstrapStatus' | 'init' | 'fill' | 'fi...
  type SyncAction (line 18) | type SyncAction = 'exportRules' | 'exportDocs' | 'exportAgents' | 'expor...
  type PlanAction (line 19) | type PlanAction = 'link' | 'getLinked' | 'getDetails' | 'getForPhase' | ...
  type AgentAction (line 20) | type AgentAction = 'discover' | 'getInfo' | 'orchestrate' | 'getSequence...
  type SkillAction (line 21) | type SkillAction = 'list' | 'getContent' | 'getForPhase' | 'scaffold' | ...
  type HarnessAction (line 22) | type HarnessAction =
  type ExploreParams (line 56) | interface ExploreParams {
  type ContextParams (line 71) | interface ContextParams {
  type SyncParams (line 107) | interface SyncParams {
  type PlanParams (line 128) | interface PlanParams {
  type AgentParams (line 146) | interface AgentParams {
  type SkillParams (line 157) | interface SkillParams {
  type HarnessParams (line 167) | interface HarnessParams {

FILE: src/services/mcp/gateway/workflowAdvance.ts
  type WorkflowAdvanceParams (line 19) | interface WorkflowAdvanceParams {
  type WorkflowAdvanceOptions (line 25) | interface WorkflowAdvanceOptions {
  function handleWorkflowAdvance (line 38) | async function handleWorkflowAdvance(

FILE: src/services/mcp/gateway/workflowInit.ts
  type WorkflowInitParams (line 19) | interface WorkflowInitParams {
  type WorkflowInitOptions (line 30) | interface WorkflowInitOptions {
  function handleWorkflowInit (line 40) | async function handleWorkflowInit(
  function buildWorkflowEnhancementPrompt (line 123) | function buildWorkflowEnhancementPrompt(options: {
  function buildWorkflowNextSteps (line 199) | function buildWorkflowNextSteps(options: {

FILE: src/services/mcp/gateway/workflowManage.test.ts
  function parseResponse (line 10) | function parseResponse(response: { content: Array<{ text: string }> }) {

FILE: src/services/mcp/gateway/workflowManage.ts
  type WorkflowManageParams (line 20) | interface WorkflowManageParams {
  type WorkflowManageOptions (line 53) | interface WorkflowManageOptions {
  function handleWorkflowManage (line 60) | async function handleWorkflowManage(

FILE: src/services/mcp/gateway/workflowStatus.test.ts
  function parseResponse (line 9) | function parseResponse(response: { content: Array<{ text: string }> }) {

FILE: src/services/mcp/gateway/workflowStatus.ts
  type WorkflowStatusParams (line 18) | interface WorkflowStatusParams {
  type WorkflowStatusOptions (line 22) | interface WorkflowStatusOptions {
  function handleWorkflowStatus (line 29) | async function handleWorkflowStatus(

FILE: src/services/mcp/mcpServer.ts
  type MCPServerOptions (line 56) | interface MCPServerOptions {
  class AIContextMCPServer (line 67) | class AIContextMCPServer {
    method constructor (line 76) | constructor(options: MCPServerOptions = {}) {
    method registerGatewayTools (line 107) | private registerGatewayTools(): void {
    method registerResources (line 730) | private registerResources(): void {
    method registerWorkflowResources (line 821) | private registerWorkflowResources(): void {
    method initializeRepoPath (line 891) | private async initializeRepoPath(): Promise<void> {
    method findProjectRoot (line 909) | private async findProjectRoot(startPath: string): Promise<string | nul...
    method cacheRepoPathIfValid (line 932) | private cacheRepoPathIfValid(repoPath: string): void {
    method getRepoPath (line 949) | private getRepoPath(paramsRepoPath?: string): string {
    method wrapWithActionLogging (line 972) | private wrapWithActionLogging<TParams>(
    method validatePathParams (line 1013) | private validatePathParams<TParams>(params: TParams, repoPath: string)...
    method logToolResponse (line 1025) | private async logToolResponse<TParams>(
    method logToolError (line 1051) | private async logToolError<TParams>(
    method parseResponsePayload (line 1069) | private parseResponsePayload(response: MCPToolResponse): Record<string...
    method buildResultSummary (line 1080) | private buildResultSummary(payload: Record<string, unknown>): Record<s...
    method start (line 1107) | async start(): Promise<void> {
    method stop (line 1116) | async stop(): Promise<void> {
    method log (line 1125) | private log(message: string): void {
  function startMCPServer (line 1135) | async function startMCPServer(options: MCPServerOptions = {}): Promise<A...

FILE: src/services/qa/patternInferer.ts
  class PatternInferer (line 12) | class PatternInferer {
    method inferFromMap (line 13) | inferFromMap(map: CodebaseMap): DetectedFunctionalPatterns {

FILE: src/services/qa/qaService.ts
  type QAEntry (line 23) | interface QAEntry {
  type QASearchResult (line 35) | interface QASearchResult {
  type QAGenerationResult (line 44) | interface QAGenerationResult {
  class QAService (line 53) | class QAService {
    method constructor (line 59) | constructor(options?: { useLSP?: boolean }) {
    method generateFromCodebase (line 72) | async generateFromCodebase(repoPath: string): Promise<QAGenerationResu...
    method search (line 126) | async search(repoPath: string, query: string): Promise<QASearchResult[...
    method getAll (line 171) | async getAll(repoPath: string): Promise<QAEntry[]> {
    method getBySlug (line 201) | async getBySlug(repoPath: string, slug: string): Promise<QAEntry | nul...
    method generateQAForTopic (line 219) | private async generateQAForTopic(
    method generateGettingStartedAnswer (line 321) | private generateGettingStartedAnswer(stack: StackInfo, repoPath: strin...
    method generateProjectStructureAnswer (line 400) | private async generateProjectStructureAnswer(repoPath: string, stack: ...
    method generateCLICommandsAnswer (line 447) | private generateCLICommandsAnswer(stack: StackInfo): string {
    method generateCLIArgumentsAnswer (line 468) | private generateCLIArgumentsAnswer(stack: StackInfo): string {
    method generateRoutingAnswer (line 489) | private async generateRoutingAnswer(
    method generateMiddlewareAnswer (line 538) | private async generateMiddlewareAnswer(
    method generateAuthAnswer (line 564) | private generateAuthAnswer(patterns: DetectedFunctionalPatterns): stri...
    method generateDatabaseAnswer (line 582) | private generateDatabaseAnswer(patterns: DetectedFunctionalPatterns): ...
    method generateAPIEndpointsAnswer (line 600) | private async generateAPIEndpointsAnswer(
    method generateTestingAnswer (line 623) | private generateTestingAnswer(stack: StackInfo, patterns: DetectedFunc...
    method generateErrorHandlingAnswer (line 651) | private generateErrorHandlingAnswer(patterns: DetectedFunctionalPatter...
    method generateCachingAnswer (line 669) | private generateCachingAnswer(patterns: DetectedFunctionalPatterns): s...
    method generateRealtimeAnswer (line 687) | private generateRealtimeAnswer(patterns: DetectedFunctionalPatterns): ...
    method generateBackgroundJobsAnswer (line 705) | private generateBackgroundJobsAnswer(patterns: DetectedFunctionalPatte...
    method generateDeploymentAnswer (line 723) | private generateDeploymentAnswer(stack: StackInfo): string {
    method getPatternFiles (line 747) | private getPatternFiles(patterns: DetectedFunctionalPatterns, type: st...
    method findRelevantFiles (line 756) | private async findRelevantFiles(repoPath: string, patterns: string[]):...
    method saveQAEntries (line 787) | private async saveQAEntries(
    method formatQAEntry (line 806) | private formatQAEntry(entry: QAEntry): string {
    method generateQAReadme (line 827) | private generateQAReadme(entries: QAEntry[], topicResult: TopicDetecti...
    method parseQAEntry (line 854) | private parseQAEntry(content: string, filename: string): QAEntry | null {
    method calculateRelevance (line 902) | private calculateRelevance(
    method convertMapStackToStackInfo (line 955) | private convertMapStackToStackInfo(map: CodebaseMap): StackInfo {
    method shutdown (line 977) | async shutdown(): Promise<void> {

FILE: src/services/qa/topicDetector.ts
  type QATopic (line 16) | interface QATopic {
  type TopicDetectionResult (line 26) | interface TopicDetectionResult {
  type ProjectType (line 32) | type ProjectType =
  class TopicDetector (line 45) | class TopicDetector {
    method detectTopics (line 49) | detectTopics(
    method detectProjectType (line 313) | private detectProjectType(stack: StackInfo): ProjectType {
    method isCLI (line 364) | private isCLI(stack: StackInfo): boolean {
    method hasWebFramework (line 375) | private hasWebFramework(stack: StackInfo): boolean {
    method hasFrontendFramework (line 398) | private hasFrontendFramework(stack: StackInfo): boolean {

FILE: src/services/quickSync/quickSyncService.ts
  type QuickSyncServiceDependencies (line 17) | interface QuickSyncServiceDependencies {
  type QuickSyncOptions (line 23) | interface QuickSyncOptions {
  type QuickSyncResult (line 51) | interface QuickSyncResult {
  class QuickSyncService (line 58) | class QuickSyncService {
    method constructor (line 63) | constructor(deps: QuickSyncServiceDependencies) {
    method run (line 72) | async run(repoPath: string, options: QuickSyncOptions = {}): Promise<Q...
    method getStats (line 242) | async getStats(repoPath: string): Promise<{
  function createQuickSyncService (line 297) | function createQuickSyncService(deps: QuickSyncServiceDependencies): Qui...

FILE: src/services/report/reportService.ts
  type ReportServiceDependencies (line 25) | type ReportServiceDependencies = BaseDependencies;
  type ReportOptions (line 27) | interface ReportOptions {
  type WorkflowReport (line 35) | interface WorkflowReport {
  type PhaseReport (line 55) | interface PhaseReport {
  type RoleReport (line 65) | interface RoleReport {
  type TimelineEvent (line 72) | interface TimelineEvent {
  type StackReport (line 79) | interface StackReport {
  class ReportService (line 86) | class ReportService {
    method constructor (line 87) | constructor(private deps: ReportServiceDependencies) {}
    method generate (line 92) | async generate(repoPath: string, options: ReportOptions = {}): Promise...
    method output (line 134) | async output(report: WorkflowReport, options: ReportOptions = {}): Pro...
    method createWorkflowService (line 148) | private createWorkflowService(repoPath: string): WorkflowService {
    method detectStack (line 161) | private async detectStack(repoPath: string): Promise<StackReport> {
    method buildPhasesReport (line 175) | private buildPhasesReport(status: PrevcStatus): PhaseReport[] {
    method buildRolesForPhase (line 190) | private buildRolesForPhase(status: PrevcStatus, phase: string): RoleRe...
    method mapOutputs (line 204) | private mapOutputs(outputs?: Array<{ path: string } | string>): string...
    method buildTimeline (line 211) | private buildTimeline(status: PrevcStatus): TimelineEvent[] {
    method outputJson (line 247) | private async outputJson(report: WorkflowReport, options: ReportOption...
    method outputMarkdown (line 255) | private async outputMarkdown(report: WorkflowReport, options: ReportOp...
    method writeOutput (line 263) | private async writeOutput(content: string, options: ReportOptions): Pr...
    method outputConsole (line 275) | private outputConsole(report: WorkflowReport): void {
    method generateVisualDashboard (line 282) | generateVisualDashboard(report: WorkflowReport): string {
    method getStatusIcon (line 333) | private getStatusIcon(status: string): string {
    method getStatusLabel (line 343) | private getStatusLabel(status: string): string {
    method centerText (line 353) | private centerText(text: string, width: number): string {
    method padText (line 359) | private padText(text: string, width: number): string {
    method generateMarkdown (line 366) | private generateMarkdown(report: WorkflowReport): string {
    method generateSummaryTable (line 382) | private generateSummaryTable(report: WorkflowReport): string {
    method generatePhasesSection (line 396) | private generatePhasesSection(phases: PhaseReport[]): string {
    method generateTimelineSection (line 412) | private generateTimelineSection(timeline: TimelineEvent[]): string {
    method generateStackSection (line 422) | private generateStackSection(stack: StackReport): string {
    method generateRecommendationsSection (line 434) | private generateRecommendationsSection(recommendations: string[]): str...

FILE: src/services/reverseSync/importSkillsService.ts
  type ImportSkillsResult (line 26) | interface ImportSkillsResult {
  class ImportSkillsService (line 41) | class ImportSkillsService {
    method constructor (line 47) | constructor(dependencies: ReverseSyncServiceDependencies) {
    method run (line 54) | async run(
    method importSkillFiles (line 103) | async importSkillFiles(
    method resolveOptions (line 110) | private async resolveOptions(
    method importFiles (line 133) | private async importFiles(
    method importSingleSkill (line 216) | private async importSingleSkill(
    method prepareContent (line 271) | private async prepareContent(
    method addImportMetadata (line 285) | private addImportMetadata(content: string, skill: SkillFileInfo): stri...
    method mergeContent (line 333) | private async mergeContent(
    method getRenamedPath (line 357) | private async getRenamedPath(originalPath: string, sourceTool: string)...
    method logImportAction (line 381) | private logImportAction(
    method displaySummary (line 408) | private displaySummary(result: ImportSkillsResult, dryRun: boolean): v...
    method createEmptyResult (line 443) | private createEmptyResult(targetPath: string): ImportSkillsResult {

FILE: src/services/reverseSync/presets.ts
  constant SKILL_SOURCES (line 28) | const SKILL_SOURCES: RuleSource[] = getSkillsImportSources();
  constant TOOL_NAME_MAP (line 37) | const TOOL_NAME_MAP: Record<string, string> = getDirectoryPrefixMap();
  constant TOOL_DISPLAY_NAMES (line 42) | const TOOL_DISPLAY_NAMES: Record<string, string> = getDisplayNameMap();
  constant TOOL_CAPABILITIES (line 47) | const TOOL_CAPABILITIES: Record<string, ToolCapabilities> = getCapabilit...
  constant ALL_TOOL_IDS (line 52) | const ALL_TOOL_IDS = getAllToolIds();
  function getSkillSourceByName (line 61) | function getSkillSourceByName(name: string): RuleSource | undefined {
  function getAllSkillSourceNames (line 68) | function getAllSkillSourceNames(): string[] {
  function getToolIdFromPath (line 77) | function getToolIdFromPath(filePath: string): string {
  function getToolDisplayName (line 84) | function getToolDisplayName(toolId: string): string {
  function getToolCapabilities (line 91) | function getToolCapabilities(toolId: string): ToolCapabilities {

FILE: src/services/reverseSync/reverseQuickSyncService.ts
  class ReverseQuickSyncService (line 32) | class ReverseQuickSyncService {
    method constructor (line 42) | constructor(deps: ReverseSyncServiceDependencies) {
    method run (line 56) | async run(repoPath: string, options: ReverseSyncCommandFlags = {}): Pr...
    method detect (line 201) | async detect(repoPath: string): Promise<ToolDetectionResult> {
    method preview (line 208) | async preview(repoPath: string, options: ReverseSyncCommandFlags = {})...
    method resolveOptions (line 212) | private resolveOptions(
    method displaySummary (line 232) | private displaySummary(result: ReverseSyncResult, options: ReverseSync...
  function createReverseQuickSyncService (line 292) | function createReverseQuickSyncService(

FILE: src/services/reverseSync/skillsDetector.ts
  class SkillsDetector (line 14) | class SkillsDetector {
    method detectSkills (line 18) | async detectSkills(repoPath: string, autoDetect: boolean = true): Prom...
    method detectFromPaths (line 107) | async detectFromPaths(sourcePaths: string[], repoPath: string): Promis...
    method createSkillFileInfo (line 171) | private async createSkillFileInfo(
    method parseSkillMetadata (line 213) | private parseSkillMetadata(content: string): SkillMetadata | undefined {
    method parseArrayValue (line 263) | private parseArrayValue(value: string): string[] {
    method slugToName (line 274) | private slugToName(slug: string): string {

FILE: src/services/reverseSync/toolDetector.ts
  class ToolDetector (line 21) | class ToolDetector {
    method constructor (line 26) | constructor() {
    method detect (line 36) | async detect(repoPath: string): Promise<ToolDetectionResult> {
    method detectTool (line 67) | async detectTool(repoPath: string, toolId: string): Promise<ToolPresen...
    method groupByTool (line 75) | private groupByTool(
    method getToolIdForRule (line 157) | private getToolIdForRule(rule: RuleFileInfo): string {
  function formatDetectionSummary (line 188) | function formatDetectionSummary(result: ToolDetectionResult): string {

FILE: src/services/reverseSync/types.ts
  type MergeStrategy (line 16) | type MergeStrategy = 'skip' | 'overwrite' | 'merge' | 'rename';
  type ToolPresence (line 25) | interface ToolPresence {
  type ToolDetectionResult (line 50) | interface ToolDetectionResult {
  type SkillMetadata (line 70) | interface SkillMetadata {
  type SkillFileInfo (line 81) | interface SkillFileInfo {
  type SkillDetectionResult (line 101) | interface SkillDetectionResult {
  type ImportMetadata (line 113) | interface ImportMetadata {
  type ReverseSyncCommandFlags (line 135) | interface ReverseSyncCommandFlags {
  type ReverseSyncOptions (line 151) | interface ReverseSyncOptions {
  type ImportAction (line 169) | type ImportAction = 'created' | 'overwritten' | 'merged' | 'renamed' | '...
  type ImportContentType (line 174) | type ImportContentType = 'rule' | 'agent' | 'skill';
  type ImportedFileRecord (line 179) | interface ImportedFileRecord {
  type ReverseSyncResult (line 191) | interface ReverseSyncResult {
  type ImportSkillsOptions (line 206) | interface ImportSkillsOptions {
  type ImportSkillsCommandFlags (line 220) | interface ImportSkillsCommandFlags {
  type ReverseSyncServiceDependencies (line 235) | interface ReverseSyncServiceDependencies {

FILE: src/services/semantic/codebaseAnalyzer.test.ts
  function createTempOutput (line 78) | function createTempOutput(prefix: string): Promise<string> {

FILE: src/services/semantic/codebaseAnalyzer.ts
  constant DEFAULT_OPTIONS (line 32) | const DEFAULT_OPTIONS: Required<AnalyzerOptions> = {
  class CodebaseAnalyzer (line 41) | class CodebaseAnalyzer {
    method constructor (line 46) | constructor(options: AnalyzerOptions = {}) {
    method analyze (line 56) | async analyze(projectPath: string): Promise<SemanticContext> {
    method findCodeFiles (line 82) | private async findCodeFiles(projectPath: string): Promise<string[]> {
    method analyzeFiles (line 116) | private async analyzeFiles(files: string[]): Promise<Map<string, FileA...
    method buildBaseContext (line 134) | private buildBaseContext(
    method resolveImportPath (line 212) | private resolveImportPath(
    method fileExistsSync (line 243) | private fileExistsSync(filePath: string): boolean {
    method detectArchitecture (line 252) | private detectArchitecture(
    method detectLayers (line 267) | private detectLayers(
    method detectPatterns (line 358) | private detectPatterns(analyses: Map<string, FileAnalysis>): DetectedP...
    method findEntryPoints (line 458) | private findEntryPoints(
    method findPublicAPI (line 481) | private findPublicAPI(analyses: Map<string, FileAnalysis>): ExtractedS...
    method calculateLayerDependencies (line 502) | private calculateLayerDependencies(
    method getSummary (line 546) | getSummary(context: SemanticContext, projectPath: string): string {
    method clearCache (line 591) | clearCache(): void {
    method shutdown (line 598) | async shutdown(): Promise<void> {
    method enhanceWithLSP (line 608) | private async enhanceWithLSP(
    method detectFunctionalPatterns (line 673) | async detectFunctionalPatterns(projectPath: string): Promise<DetectedF...
    method detectAuthPattern (line 738) | private detectAuthPattern(
    method detectDatabasePattern (line 792) | private detectDatabasePattern(
    method detectApiPattern (line 848) | private detectApiPattern(
    method detectCachePattern (line 902) | private detectCachePattern(
    method detectQueuePattern (line 943) | private detectQueuePattern(
    method detectWebSocketPattern (line 984) | private detectWebSocketPattern(
    method detectLoggingPattern (line 1025) | private detectLoggingPattern(
    method detectValidationPattern (line 1066) | private detectValidationPattern(
    method detectErrorHandlingPattern (line 1107) | private detectErrorHandlingPattern(
    method detectTestingPattern (line 1148) | private detectTestingPattern(
    method traceFlow (line 1191) | async traceFlow(
    method traceCallsFromFile (line 1260) | private async traceCallsFromFile(
    method generateMermaidDiagram (line 1363) | private generateMermaidDiagram(nodes: FlowNode[], edges: FlowEdge[]): ...

FILE: src/services/semantic/contextBuilder.ts
  type ContextBuilderOptions (line 19) | interface ContextBuilderOptions extends AnalyzerOptions {
  type ContextFormat (line 30) | type ContextFormat = 'documentation' | 'playbook' | 'plan' | 'compact';
  constant DEFAULT_OPTIONS (line 32) | const DEFAULT_OPTIONS: Required<ContextBuilderOptions> = {
  class SemanticContextBuilder (line 45) | class SemanticContextBuilder {
    method constructor (line 51) | constructor(options: ContextBuilderOptions = {}) {
    method analyze (line 59) | async analyze(projectPath: string): Promise<SemanticContext> {
    method buildDocumentationContext (line 72) | async buildDocumentationContext(
    method buildPlaybookContext (line 105) | async buildPlaybookContext(
    method buildPlanContext (line 135) | async buildPlanContext(
    method buildCompactContext (line 169) | async buildCompactContext(projectPath: string): Promise<string> {
    method buildSkillContext (line 183) | async buildSkillContext(
    method getSemanticContext (line 227) | async getSemanticContext(projectPath: string): Promise<SemanticContext> {
    method formatArchitectureOverview (line 233) | private formatArchitectureOverview(context: SemanticContext): string {
    method formatPublicAPI (line 255) | private formatPublicAPI(context: SemanticContext, projectPath: string)...
    method formatSymbolIndex (line 276) | private formatSymbolIndex(context: SemanticContext, projectPath: strin...
    method formatSymbolLine (line 307) | private formatSymbolLine(symbol: ExtractedSymbol, projectPath: string)...
    method formatTargetFileContext (line 330) | private formatTargetFileContext(
    method formatDependencyOverview (line 362) | private formatDependencyOverview(context: SemanticContext, projectPath...
    method formatRelevantLayers (line 388) | private formatRelevantLayers(
    method formatRelevantPatterns (line 415) | private formatRelevantPatterns(patterns: DetectedPattern[]): string {
    method formatKeyFilesForAgent (line 434) | private formatKeyFilesForAgent(
    method formatRelevantSymbolsForAgent (line 465) | private formatRelevantSymbolsForAgent(
    method formatFullArchitecture (line 493) | private formatFullArchitecture(
    method formatAllPatterns (line 525) | private formatAllPatterns(context: SemanticContext): string {
    method formatEntryPoints (line 541) | private formatEntryPoints(context: SemanticContext): string {
    method formatLayerDependencies (line 554) | private formatLayerDependencies(context: SemanticContext): string {
    method formatSymbolsByLayer (line 571) | private formatSymbolsByLayer(
    method formatCompactSymbolList (line 601) | private formatCompactSymbolList(
    method getRelevantLayersForAgent (line 624) | private getRelevantLayersForAgent(
    method getRelevantPatternsForAgent (line 651) | private getRelevantPatternsForAgent(
    method getKeyPatternsForAgent (line 671) | private getKeyPatternsForAgent(agentType: string): RegExp[] {
    method getRelevantPatternsForSkill (line 692) | private getRelevantPatternsForSkill(
    method getKeyPatternsForSkill (line 717) | private getKeyPatternsForSkill(skillType: string): RegExp[] {
    method formatKeyFilesForSkill (line 734) | private formatKeyFilesForSkill(
    method formatRelevantSymbolsForSkill (line 765) | private formatRelevantSymbolsForSkill(
    method truncateToLimit (line 793) | private truncateToLimit(content: string): string {
    method clearCache (line 807) | clearCache(): void {
    method shutdown (line 816) | async shutdown(): Promise<void> {

FILE: src/services/semantic/contextCache.ts
  type CacheEntry (line 20) | interface CacheEntry {
  type ContextCacheOptions (line 29) | interface ContextCacheOptions {
  constant DEFAULT_TTL_MS (line 36) | const DEFAULT_TTL_MS = 5 * 60 * 1000;
  constant DEFAULT_WATCH_DIRS (line 37) | const DEFAULT_WATCH_DIRS = ['src', '.context', 'lib', 'packages'];
  class ContextCache (line 39) | class ContextCache {
    method constructor (line 44) | constructor(options: ContextCacheOptions = {}) {
    method get (line 56) | async get(repoPath: string, contextType: string): Promise<string | nul...
    method set (line 87) | async set(repoPath: string, contextType: string, content: string): Pro...
    method invalidateRepo (line 101) | invalidateRepo(repoPath: string): void {
    method clear (line 113) | clear(): void {
    method size (line 120) | get size(): number {
    method buildKey (line 127) | private buildKey(repoPath: string, contextType: string): string {
    method normalizeRepoPath (line 134) | private normalizeRepoPath(repoPath: string): string {
    method computeMtimeHash (line 143) | private async computeMtimeHash(repoPath: string): Promise<string> {

FILE: src/services/semantic/lsp/lspLayer.ts
  type LSPMessage (line 18) | interface LSPMessage {
  type PendingRequest (line 27) | interface PendingRequest {
  constant LSP_SERVER_CONFIGS (line 33) | const LSP_SERVER_CONFIGS: Record<string, LSPServerConfig> = {
  constant REQUEST_TIMEOUT_MS (line 51) | const REQUEST_TIMEOUT_MS = 10000;
  class LSPLayer (line 53) | class LSPLayer {
    method detectLanguage (line 60) | private detectLanguage(filePath: string): SupportedLanguage | null {
    method getServerConfig (line 65) | private getServerConfig(language: string): LSPServerConfig | null {
    method ensureServer (line 69) | async ensureServer(language: string, projectPath: string): Promise<boo...
    method handleServerData (line 151) | private handleServerData(language: string, data: Buffer): void {
    method handleMessage (line 177) | private handleMessage(message: LSPMessage): void {
    method sendRequest (line 191) | private sendRequest(language: string, method: string, params: unknown)...
    method sendNotification (line 213) | private sendNotification(language: string, method: string, params: unk...
    method sendMessage (line 222) | private sendMessage(language: string, message: LSPMessage): void {
    method cleanup (line 236) | private cleanup(language: string): void {
    method getTypeInfo (line 249) | async getTypeInfo(
    method findReferences (line 277) | async findReferences(
    method getDefinition (line 310) | async getDefinition(
    method findImplementations (line 343) | async findImplementations(
    method parseHoverResult (line 375) | private parseHoverResult(contents: unknown): TypeInfo {
    method shutdown (line 399) | async shutdown(): Promise<void> {
    method isServerAvailable (line 419) | isServerAvailable(language: string): boolean {
    method getAvailableLanguages (line 423) | getAvailableLanguages(): string[] {

FILE: src/services/semantic/semanticSnapshotService.ts
  type SemanticSnapshotSection (line 18) | type SemanticSnapshotSection =
  type SnapshotFileSection (line 30) | type SnapshotFileSection = Exclude<SemanticSnapshotSection, 'all' | 'met...
  type SemanticSnapshotManifest (line 32) | interface SemanticSnapshotManifest extends SemanticSnapshotMetadata {
  type SemanticSnapshotWriteOptions (line 37) | interface SemanticSnapshotWriteOptions {
  type SemanticSnapshotWriteResult (line 46) | interface SemanticSnapshotWriteResult {
  type SemanticSnapshotReadOptions (line 53) | interface SemanticSnapshotReadOptions {
  type SemanticSnapshotSectionResult (line 58) | interface SemanticSnapshotSectionResult {
  type SemanticSnapshotRefreshReason (line 66) | type SemanticSnapshotRefreshReason = 'fresh' | 'stale' | 'missing';
  type SemanticSnapshotEnsureSummaryResult (line 68) | interface SemanticSnapshotEnsureSummaryResult {
  type SemanticSnapshotEnsureSectionResult (line 78) | interface SemanticSnapshotEnsureSectionResult extends SemanticSnapshotSe...
  type SnapshotArtifacts (line 84) | interface SnapshotArtifacts {
  constant SNAPSHOT_SCHEMA_VERSION (line 89) | const SNAPSHOT_SCHEMA_VERSION = '2.0.0';
  constant SNAPSHOT_DIRNAME (line 90) | const SNAPSHOT_DIRNAME = path.join('cache', 'semantic');
  constant MANIFEST_FILENAME (line 91) | const MANIFEST_FILENAME = 'manifest.json';
  constant SUMMARY_FILENAME (line 92) | const SUMMARY_FILENAME = 'summary.json';
  constant VERSIONS_DIRNAME (line 93) | const VERSIONS_DIRNAME = 'versions';
  constant MAX_REFRESH_ATTEMPTS (line 94) | const MAX_REFRESH_ATTEMPTS = 3;
  constant MAX_VERSION_HISTORY (line 95) | const MAX_VERSION_HISTORY = 3;
  constant SECTION_FILENAMES (line 97) | const SECTION_FILENAMES: Record<SnapshotFileSection, string> = {
  constant LEGACY_CODEBASE_MAP_PATH (line 108) | const LEGACY_CODEBASE_MAP_PATH = path.join('docs', 'codebase-map.json');
  constant FINGERPRINT_IGNORE_PATTERNS (line 110) | const FINGERPRINT_IGNORE_PATTERNS = [
  constant FINGERPRINT_ROOT_FILES (line 121) | const FINGERPRINT_ROOT_FILES = new Set([
  constant FINGERPRINT_CODE_EXTENSIONS (line 146) | const FINGERPRINT_CODE_EXTENSIONS = new Set([
  class SemanticSnapshotService (line 161) | class SemanticSnapshotService {
    method captureRepoFingerprint (line 164) | async captureRepoFingerprint(repoPath: string): Promise<string> {
    method writeSnapshot (line 168) | async writeSnapshot(
    method ensureFreshSummary (line 198) | async ensureFreshSummary(
    method ensureFreshSection (line 227) | async ensureFreshSection(
    method readSummary (line 252) | async readSummary(
    method readSection (line 274) | async readSection(
    method refreshSnapshot (line 291) | private async refreshSnapshot(
    method inspectSummary (line 354) | private async inspectSummary(
    method inspectSection (line 393) | private async inspectSection(
    method buildSnapshotArtifacts (line 415) | private async buildSnapshotArtifacts(
    method publishSnapshotArtifacts (line 486) | private async publishSnapshotArtifacts(params: {
    method buildSectionResult (line 539) | private buildSectionResult(
    method buildSectionResultFromManifest (line 566) | private async buildSectionResultFromManifest(
    method extractSectionData (line 600) | private extractSectionData(map: CodebaseMap, section: SemanticSnapshot...
    method getSectionData (line 625) | private getSectionData(summary: CodebaseMap): Record<SnapshotFileSecti...
    method replaceFile (line 638) | private async replaceFile(targetPath: string, sourcePath: string): Pro...
    method promoteFile (line 660) | private async promoteFile(sourcePath: string, targetPath: string): Pro...
    method getSnapshotDir (line 668) | private getSnapshotDir(outputDir: string): string {
    method buildPublishedManifest (line 672) | private buildPublishedManifest(
    method createVersionId (line 693) | private createVersionId(): string {
    method pruneSnapshotVersions (line 697) | private async pruneSnapshotVersions(snapshotDir: string): Promise<void> {
    method resolveOutputDir (line 722) | private resolveOutputDir(repoPath: string, outputDir?: string): string {
    method isFresh (line 728) | private async isFresh(repoPath: string, expectedFingerprint: string): ...
    method computeRepoFingerprint (line 732) | private async computeRepoFingerprint(repoPath: string): Promise<string> {
    method isFingerprintRelevant (line 759) | private isFingerprintRelevant(relativePath: string): boolean {

FILE: src/services/semantic/treeSitter/treeSitterLayer.ts
  type CacheEntry (line 19) | interface CacheEntry {
  class TreeSitterLayer (line 24) | class TreeSitterLayer {
    method constructor (line 30) | constructor() {
    method initializeParsers (line 34) | private async initializeParsers(): Promise<void> {
    method analyzeFile (line 57) | async analyzeFile(filePath: string): Promise<FileAnalysis> {
    method analyzeWithTreeSitter (line 94) | private analyzeWithTreeSitter(
    method extractFromTreeSitter (line 114) | private extractFromTreeSitter(
    method extractClassFromTree (line 163) | private extractClassFromTree(node: any, filePath: string): ExtractedSy...
    method extractInterfaceFromTree (line 178) | private extractInterfaceFromTree(node: any, filePath: string): Extract...
    method extractFunctionFromTree (line 193) | private extractFunctionFromTree(node: any, filePath: string): Extracte...
    method extractTypeFromTree (line 208) | private extractTypeFromTree(node: any, filePath: string): ExtractedSym...
    method extractEnumFromTree (line 223) | private extractEnumFromTree(node: any, filePath: string): ExtractedSym...
    method extractImportFromTree (line 238) | private extractImportFromTree(node: any): ImportInfo {
    method extractExportFromTree (line 271) | private extractExportFromTree(node: any): ExportInfo | null {
    method isNodeExported (line 291) | private isNodeExported(node: any): boolean {
    method extractDocComment (line 300) | private extractDocComment(node: any): string | undefined {
    method analyzeWithRegex (line 315) | private analyzeWithRegex(
    method analyzeTypeScriptWithRegex (line 331) | private analyzeTypeScriptWithRegex(
    method analyzePythonWithRegex (line 487) | private analyzePythonWithRegex(filePath: string, content: string): Fil...
    method emptyAnalysis (line 550) | private emptyAnalysis(filePath: string, language: string): FileAnalysis {
    method clearCache (line 560) | clearCache(): void {
    method isTreeSitterAvailable (line 564) | async isTreeSitterAvailable(): Promise<boolean> {

FILE: src/services/semantic/types.ts
  type SymbolKind (line 5) | type SymbolKind = 'class' | 'interface' | 'function' | 'type' | 'variabl...
  type SymbolLocation (line 7) | interface SymbolLocation {
  type ParameterInfo (line 13) | interface ParameterInfo {
  type ExtractedSymbol (line 20) | interface ExtractedSymbol {
  type ImportInfo (line 37) | interface ImportInfo {
  type ExportInfo (line 45) | interface ExportInfo {
  type FileAnalysis (line 52) | interface FileAnalysis {
  type ArchitectureLayer (line 60) | interface ArchitectureLayer {
  type DetectedPattern (line 68) | interface DetectedPattern {
  type FunctionalPatternType (line 79) | type FunctionalPatternType =
  type FunctionalPattern (line 91) | interface FunctionalPattern {
  type PatternIndicator (line 98) | interface PatternIndicator {
  type DetectedFunctionalPatterns (line 105) | interface DetectedFunctionalPatterns {
  type FlowNode (line 122) | interface FlowNode {
  type FlowEdge (line 129) | interface FlowEdge {
  type ExecutionFlow (line 135) | interface ExecutionFlow {
  type DependencyInfo (line 142) | interface DependencyInfo {
  type ArchitectureInfo (line 147) | interface ArchitectureInfo {
  type SemanticStats (line 154) | interface SemanticStats {
  type SemanticContext (line 161) | interface SemanticContext {
  type TypeInfo (line 174) | interface TypeInfo {
  type ReferenceLocation (line 180) | interface ReferenceLocation {
  type AnalyzerOptions (line 187) | interface AnalyzerOptions {
  type LSPServerConfig (line 196) | interface LSPServerConfig {
  type SupportedLanguage (line 202) | type SupportedLanguage =
  constant LANGUAGE_EXTENSIONS (line 207) | const LANGUAGE_EXTENSIONS: Record<string, SupportedLanguage> = {
  constant DEFAULT_EXCLUDE_PATTERNS (line 219) | const DEFAULT_EXCLUDE_PATTERNS = [

FILE: src/services/shared/contentTypeRegistry.ts
  type ContentType (line 12) | interface ContentType {
  constant CONTENT_TYPE_REGISTRY (line 34) | const CONTENT_TYPE_REGISTRY: ContentType[] = [
  function getContentType (line 86) | function getContentType(id: string): ContentType | undefined {
  function getExportableContentTypes (line 93) | function getExportableContentTypes(): ContentType[] {
  function getImportableContentTypes (line 100) | function getImportableContentTypes(): ContentType[] {
  function getContentTypeIds (line 107) | function getContentTypeIds(): string[] {
  function hasContentType (line 114) | function hasContentType(id: string): boolean {
  function registerContentType (line 122) | function registerContentType(contentType: ContentType): void {
  function getContextPath (line 132) | function getContextPath(id: string): string | undefined {
  function getIndexFile (line 139) | function getIndexFile(id: string): string | undefined {

FILE: src/services/shared/contextLayout.ts
  type ContextLayoutClassification (line 8) | type ContextLayoutClassification = 'versioned' | 'local' | 'runtime';
  type ContextLayoutEntry (line 10) | interface ContextLayoutEntry {
  constant CONTEXT_LAYOUT_REGISTRY (line 18) | const CONTEXT_LAYOUT_REGISTRY: ContextLayoutEntry[] = [
  function getContextLayoutByClassification (line 140) | function getContextLayoutByClassification(
  function getUntrackedContextLayoutEntries (line 146) | function getUntrackedContextLayoutEntries(): ContextLayoutEntry[] {

FILE: src/services/shared/contextRootResolver.ts
  function resolveContextPath (line 17) | function resolveContextPath(repoPath?: string): string {
  type SimpleContextResult (line 28) | interface SimpleContextResult {
  function resolveSimpleContext (line 42) | async function resolveSimpleContext(repoPath?: string): Promise<SimpleCo...
  function getContextPath (line 58) | async function getContextPath(repoPath: string = process.cwd()): Promise...
  function getProjectRoot (line 67) | async function getProjectRoot(repoPath: string = process.cwd()): Promise...
  type ContextResolutionResult (line 75) | interface ContextResolutionResult {
  function resolveContextRoot (line 82) | async function resolveContextRoot(options?: { startPath?: string; valida...

FILE: src/services/shared/globPatterns.ts
  constant COMMON_IGNORES (line 13) | const COMMON_IGNORES = [
  constant CODE_EXTENSIONS (line 31) | const CODE_EXTENSIONS = [
  constant DOC_EXTENSIONS (line 49) | const DOC_EXTENSIONS = ['md', 'mdx', 'txt', 'rst'] as const;
  constant CONFIG_PATTERNS (line 54) | const CONFIG_PATTERNS = [
  type GlobFilesOptions (line 69) | interface GlobFilesOptions {
  function globFiles (line 79) | async function globFiles(
  function globMultiple (line 108) | async function globMultiple(
  function buildExtensionPattern (line 124) | function buildExtensionPattern(extensions: readonly string[]): string {
  function shouldIgnore (line 134) | function shouldIgnore(filePath: string): boolean {

FILE: src/services/shared/pathHelpers.ts
  type ContextPaths (line 18) | interface ContextPaths {
  type ContextPathsWithResolution (line 31) | interface ContextPathsWithResolution extends ContextPaths {
  function resolveContextPaths (line 40) | function resolveContextPaths(repoPath: string): ContextPaths {
  function resolveContextPathsAsync (line 59) | async function resolveContextPathsAsync(
  function resolveAbsolutePath (line 84) | function resolveAbsolutePath(
  function ensureDirectory (line 98) | async function ensureDirectory(dirPath: string): Promise<void> {
  function ensureParentDirectory (line 105) | async function ensureParentDirectory(filePath: string): Promise<void> {
  function getRelativePath (line 112) | function getRelativePath(fullPath: string, basePath: string): string {
  function pathExists (line 119) | async function pathExists(targetPath: string): Promise<boolean> {
  function isDirectory (line 126) | async function isDirectory(targetPath: string): Promise<boolean> {
  function isFile (line 138) | async function isFile(targetPath: string): Promise<boolean> {
  function normalizePath (line 150) | function normalizePath(inputPath: string): string {
  function deduplicatePaths (line 157) | function deduplicatePaths(paths: string[]): string[] {
  function getExtension (line 164) | function getExtension(filePath: string): string {
  function getBasename (line 172) | function getBasename(filePath: string): string {
  function joinPaths (line 179) | function joinPaths(...parts: (string | undefined)[]): string {

FILE: src/services/shared/toolRegistry.ts
  type ToolCapabilities (line 15) | interface ToolCapabilities {
  type ToolPaths (line 21) | interface ToolPaths {
  type ToolDefinition (line 46) | interface ToolDefinition {
  constant TOOL_REGISTRY (line 67) | const TOOL_REGISTRY: ToolDefinition[] = [
  function getToolById (line 405) | function getToolById(id: string): ToolDefinition | undefined {
  function getAllToolIds (line 412) | function getAllToolIds(): string[] {
  function getToolsWithCapability (line 419) | function getToolsWithCapability(capability: keyof ToolCapabilities): Too...
  function getToolIdFromPath (line 426) | function getToolIdFromPath(filePath: string): string {
  function getToolDisplayName (line 458) | function getToolDisplayName(toolId: string): string {
  function getToolCapabilities (line 466) | function getToolCapabilities(toolId: string): ToolCapabilities {
  function getDirectoryPrefixMap (line 474) | function getDirectoryPrefixMap(): Record<string, string> {
  function getDisplayNameMap (line 485) | function getDisplayNameMap(): Record<string, string> {
  function getCapabilitiesMap (line 496) | function getCapabilitiesMap(): Record<string, ToolCapabilities> {
  function getRulesExportPresets (line 511) | function getRulesExportPresets(): Record<string, Array<{
  function getAgentsSyncPresets (line 538) | function getAgentsSyncPresets(): Record<string, {
  function getSkillsExportPresets (line 563) | function getSkillsExportPresets(): Record<string, Array<{
  function getRulesImportSources (line 586) | function getRulesImportSources(): Array<{
  function getAgentsImportSources (line 608) | function getAgentsImportSources(): Array<{
  function getSkillsImportSources (line 627) | function getSkillsImportSources(): Array<{

FILE: src/services/shared/types.ts
  type BaseDependencies (line 14) | interface BaseDependencies {
  type OperationResult (line 23) | interface OperationResult {
  type OperationError (line 33) | interface OperationError {
  type FileInfo (line 41) | interface FileInfo {
  type DetectionResult (line 50) | interface DetectionResult<T extends FileInfo = FileInfo> {
  type DryRunOptions (line 58) | interface DryRunOptions {
  function createEmptyResult (line 67) | function createEmptyResult(): OperationResult {
  function mergeResults (line 79) | function mergeResults(...results: OperationResult[]): OperationResult {
  function addError (line 94) | function addError(

FILE: src/services/shared/uiHelpers.ts
  type SpinnerStatus (line 16) | type SpinnerStatus = 'success' | 'fail' | 'warn' | 'info';
  function withSpinner (line 21) | async function withSpinner<T>(
  function displayOperationSummary (line 67) | function displayOperationSummary(
  function displayProgressBar (line 111) | function displayProgressBar(
  function displayPhaseIndicator (line 144) | function displayPhaseIndicator(
  function createBox (line 189) | function createBox(

FILE: src/services/stack/projectTypeClassifier.ts
  constant PROJECT_TYPES (line 10) | const PROJECT_TYPES = [
  type ProjectType (line 22) | type ProjectType = (typeof PROJECT_TYPES)[number];
  type ProjectClassification (line 24) | interface ProjectClassification {
  constant FRAMEWORK_CATEGORIES (line 35) | const FRAMEWORK_CATEGORIES = {
  constant CONFIDENCE_THRESHOLDS (line 86) | const CONFIDENCE_THRESHOLDS = {
  type ExtendedStackInfo (line 94) | interface ExtendedStackInfo extends StackInfo {
  function matchesCategory (line 104) | function matchesCategory(frameworks: string[], category: readonly string...
  function getMatchingFrameworks (line 113) | function getMatchingFrameworks(frameworks: string[], category: readonly ...
  function classifyProject (line 122) | function classifyProject(stack: StackInfo | ExtendedStackInfo): ProjectC...
  constant TYPE_PRIORITY (line 225) | const TYPE_PRIORITY: readonly ProjectType[] = [
  function prioritizeTypes (line 239) | function prioritizeTypes(detectedTypes: ProjectType[]): {
  function calculateConfidence (line 262) | function calculateConfidence(reasoningCount: number): 'high' | 'medium' ...
  function detectCLILibraries (line 275) | function detectCLILibraries(dependencies: Record<string, string>): strin...
  function isLibraryPackage (line 282) | function isLibraryPackage(packageJson: {

FILE: src/services/stack/scaffoldFilter.ts
  constant CORE_AGENTS (line 19) | const CORE_AGENTS: readonly AgentType[] = [
  constant CORE_DOCS (line 32) | const CORE_DOCS: readonly string[] = [
  constant CORE_SKILLS (line 42) | const CORE_SKILLS: readonly BuiltInSkillType[] = [
  constant EXTRA_AGENTS_BY_TYPE (line 55) | const EXTRA_AGENTS_BY_TYPE: Record<ProjectType, readonly AgentType[]> = {
  constant EXTRA_DOCS_BY_TYPE (line 70) | const EXTRA_DOCS_BY_TYPE: Record<ProjectType, readonly string[]> = {
  constant EXTRA_SKILLS_BY_TYPE (line 85) | const EXTRA_SKILLS_BY_TYPE: Record<ProjectType, readonly BuiltInSkillTyp...
  function buildAgentMatrix (line 98) | function buildAgentMatrix(): Record<ProjectType, Record<AgentType, boole...
  function buildDocsMatrix (line 113) | function buildDocsMatrix(): Record<ProjectType, Record<string, boolean>> {
  function buildSkillsMatrix (line 128) | function buildSkillsMatrix(): Record<ProjectType, Record<BuiltInSkillTyp...
  constant AGENT_FILTER_MATRIX (line 147) | const AGENT_FILTER_MATRIX = buildAgentMatrix();
  constant DOCS_FILTER_MATRIX (line 153) | const DOCS_FILTER_MATRIX = buildDocsMatrix();
  constant SKILLS_FILTER_MATRIX (line 159) | const SKILLS_FILTER_MATRIX = buildSkillsMatrix();
  function getAgentsForProjectType (line 165) | function getAgentsForProjectType(projectType: ProjectType): AgentType[] {
  function getDocsForProjectType (line 174) | function getDocsForProjectType(projectType: ProjectType): string[] {
  function getSkillsForProjectType (line 183) | function getSkillsForProjectType(projectType: ProjectType): BuiltInSkill...
  function getFilteredScaffolds (line 191) | function getFilteredScaffolds(projectType: ProjectType): {
  function shouldIncludeAgent (line 206) | function shouldIncludeAgent(projectType: ProjectType, agent: AgentType):...
  function shouldIncludeDoc (line 214) | function shouldIncludeDoc(projectType: ProjectType, doc: string): boolean {
  function shouldIncludeSkill (line 222) | function shouldIncludeSkill(projectType: ProjectType, skill: BuiltInSkil...
  function validateConfiguration (line 231) | function validateConfiguration(): void {

FILE: src/services/stack/stackDetector.ts
  type StackInfo (line 11) | interface StackInfo {
  type DetectionRule (line 29) | interface DetectionRule {
  constant DETECTION_RULES (line 38) | const DETECTION_RULES: DetectionRule[] = [
  constant LANGUAGE_EXTENSIONS (line 157) | const LANGUAGE_EXTENSIONS: Record<string, string> = {
  class StackDetector (line 180) | class StackDetector {
    method detect (line 184) | async detect(repoPath: string): Promise<StackInfo> {
    method getRecommendedAgents (line 273) | getRecommendedAgents(stack: StackInfo): string[] {
    method getRecommendedRules (line 309) | getRecommendedRules(stack: StackInfo): string[] {
    method checkFileExists (line 331) | private async checkFileExists(basePath: string, pattern: string): Prom...
    method countLanguagesByExtension (line 351) | private async countLanguagesByExtension(basePath: string): Promise<Rec...
    method hasCI (line 375) | private async hasCI(basePath: string): Promise<boolean> {
    method analyzePackageJson (line 399) | private async analyzePackageJson(basePath: string): Promise<{

FILE: src/services/sync/markdownReferenceHandler.ts
  function getTargetFilename (line 5) | function getTargetFilename(agent: AgentFileInfo, options: HandlerOptions...
  function createMarkdownReferences (line 10) | async function createMarkdownReferences(
  function generateReferenceMarkdown (line 61) | function generateReferenceMarkdown(
  function formatAgentTitle (line 117) | function formatAgentTitle(name: string): string {

FILE: src/services/sync/presets.ts
  function buildTargetPresets (line 8) | function buildTargetPresets(): Record<Exclude<PresetName, 'all'>, Target...
  constant TARGET_PRESETS (line 27) | const TARGET_PRESETS: Record<Exclude<PresetName, 'all'>, TargetPreset> =...
  function resolvePresets (line 29) | function resolvePresets(presetName: PresetName): TargetPreset[] {
  function getPresetByPath (line 38) | function getPresetByPath(targetPath: string): TargetPreset | undefined {
  function getAllPresetNames (line 53) | function getAllPresetNames(): PresetName[] {

FILE: src/services/sync/symlinkHandler.ts
  function getTargetFilename (line 5) | function getTargetFilename(agent: AgentFileInfo, options: HandlerOptions...
  function createSymlinks (line 10) | async function createSymlinks(
  function createPlatformSymlink (line 66) | async function createPlatformSymlink(
  function checkSymlinkSupport (line 89) | async function checkSymlinkSupport(): Promise<{

FILE: src/services/sync/syncService.ts
  class SyncService (line 20) | class SyncService {
    method constructor (line 25) | constructor(dependencies: SyncServiceDependencies) {
    method run (line 31) | async run(rawOptions: SyncCommandFlags): Promise<SyncRunResult> {
    method resolveOptions (line 95) | private async resolveOptions(rawOptions: SyncCommandFlags): Promise<Sy...
    method validateSource (line 136) | private async validateSource(sourcePath: string): Promise<void> {
    method discoverAgentFiles (line 148) | private async discoverAgentFiles(sourcePath: string): Promise<AgentFil...
    method syncToTarget (line 173) | private async syncToTarget(
    method displayConfig (line 235) | private displayConfig(options: SyncOptions): void {
    method displaySummary (line 252) | private displaySummary(results: SyncResult[], dryRun: boolean): void {

FILE: src/services/sync/types.ts
  type SyncMode (line 4) | type SyncMode = 'symlink' | 'markdown';
  type PresetName (line 6) | type PresetName = string;
  type TargetPreset (line 8) | interface TargetPreset {
  type SyncCommandFlags (line 15) | interface SyncCommandFlags {
  type SyncServiceDependencies (line 25) | interface SyncServiceDependencies {
  type SyncOptions (line 31) | interface SyncOptions {
  type SyncResult (line 40) | interface SyncResult {
  type AgentFileInfo (line 48) | interface AgentFileInfo {
  type HandlerOptions (line 55) | interface HandlerOptions {
  type HandlerResult (line 62) | interface HandlerResult {
  type SyncRunResult (line 69) | interface SyncRunResult {

FILE: src/services/workflow/autoAdvance.ts
  type AutoAdvanceResult (line 16) | interface AutoAdvanceResult {
  constant PHASE_OUTPUT_PATTERNS (line 26) | const PHASE_OUTPUT_PATTERNS: Record<PrevcPhase, string[]> = {
  constant PHASE_MIN_FILES (line 70) | const PHASE_MIN_FILES: Record<PrevcPhase, number> = {
  class AutoAdvanceDetector (line 78) | class AutoAdvanceDetector {
    method constructor (line 82) | constructor(repoPath: string) {
    method checkAutoAdvance (line 90) | async checkAutoAdvance(
    method getExpectedOutputTypes (line 152) | private getExpectedOutputTypes(phase: PrevcPhase): string[] {
    method watchForOutputs (line 167) | async watchForOutputs(
    method validatePhaseOutputs (line 208) | async validatePhaseOutputs(

FILE: src/services/workflow/workflowService.ts
  type WorkflowHarnessStatus (line 49) | interface WorkflowHarnessStatus {
  class HarnessWorkflowBlockedError (line 69) | class HarnessWorkflowBlockedError extends Error {
    method constructor (line 70) | constructor(
  type WorkflowServiceDependencies (line 84) | interface WorkflowServiceDependencies {
  type WorkflowInitOptions (line 96) | interface WorkflowInitOptions {
  class WorkflowService (line 114) | class WorkflowService {
    method constructor (line 127) | constructor(
    method create (line 159) | static async create(
    method hasWorkflow (line 169) | async hasWorkflow(): Promise<boolean> {
    method init (line 176) | async init(options: WorkflowInitOptions): Promise<PrevcStatus> {
    method getStatus (line 240) | async getStatus(): Promise<PrevcStatus> {
    method getSummary (line 247) | async getSummary(): Promise<WorkflowSummary> {
    method getFormattedStatus (line 254) | async getFormattedStatus(): Promise<string> {
    method advance (line 313) | async advance(outputs?: string[], options?: { force?: boolean }): Prom...
    method checkGates (line 364) | async checkGates(): Promise<GateCheckResult> {
    method setSettings (line 371) | async setSettings(settings: Partial<WorkflowSettings>): Promise<Workfl...
    method getSettings (line 387) | async getSettings(): Promise<WorkflowSettings> {
    method listAvailableSensors (line 391) | listAvailableSensors(): Array<Pick<HarnessSensorDefinition, 'id' | 'na...
    method setAutonomousMode (line 402) | async setAutonomousMode(enabled: boolean): Promise<WorkflowSettings> {
    method markPlanCreated (line 415) | async markPlanCreated(planSlug: string): Promise<void> {
    method approvePlan (line 428) | async approvePlan(approver: PrevcRole | string, notes?: string): Promi...
    method getApproval (line 442) | async getApproval(): Promise<PlanApproval | undefined> {
    method handoff (line 449) | async handoff(
    method getPhaseOrchestration (line 501) | async getPhaseOrchestration(phase: PrevcPhase): Promise<PhaseOrchestra...
    method getNextAgentSuggestion (line 508) | getNextAgentSuggestion(currentAgent: string): { agent: string; reason:...
    method startCollaboration (line 515) | async startCollaboration(
    method contributeToCollaboration (line 535) | contributeToCollaboration(
    method endCollaboration (line 551) | async endCollaboration(sessionId: string): Promise<CollaborationSynthe...
    method getRecommendedActions (line 558) | async getRecommendedActions(): Promise<string[]> {
    method isComplete (line 565) | async isComplete(): Promise<boolean> {
    method updateTask (line 572) | async updateTask(task: string): Promise<void> {
    method startRole (line 585) | async startRole(role: PrevcRole): Promise<void> {
    method completeRole (line 601) | async completeRole(role: PrevcRole, outputs: string[]): Promise<void> {
    method getHarnessStatus (line 618) | async getHarnessStatus(): Promise<WorkflowHarnessStatus | null> {
    method checkpointHarnessSession (line 674) | async checkpointHarnessSession(
    method recordHarnessArtifact (line 702) | async recordHarnessArtifact(input: {
    method defineHarnessTask (line 723) | async defineHarnessTask(input: {
    method runHarnessSensors (line 756) | async runHarnessSensors(sensorIds: string[], metadata?: Record<string,...
    method ensureHarnessSession (line 780) | private async ensureHarnessSession(
    method requireHarnessBinding (line 813) | private async requireHarnessBinding(): Promise<WorkflowHarnessBinding> {
    method loadHarnessBinding (line 818) | private async loadHarnessBinding(): Promise<WorkflowHarnessBinding | n...
    method saveHarnessBinding (line 822) | private async saveHarnessBinding(binding: WorkflowHarnessBinding): Pro...
    method registerDefaultSensors (line 826) | private registerDefaultSensors(): void {
    method hasPackageScript (line 857) | private async hasPackageScript(scriptName: string): Promise<boolean> {
    method executeShellSensor (line 867) | private async executeShellSensor(command: string, name: string) {
    method trimEvidence (line 898) | private trimEvidence(value?: string, maxLength: number = 2000): string...

FILE: src/types.ts
  type FileInfo (line 1) | interface FileInfo {
  type TopLevelDirectoryStats (line 10) | interface TopLevelDirectoryStats {
  type RepoStructure (line 16) | interface RepoStructure {
  type AIProvider (line 25) | type AIProvider = 'openrouter' | 'openai' | 'anthropic' | 'google';
  type LLMConfig (line 27) | interface LLMConfig {
  type CLIOptions (line 34) | interface CLIOptions {
  type AgentPrompt (line 48) | interface AgentPrompt {
  type TokenUsage (line 56) | interface TokenUsage {
  type UsageStats (line 62) | interface UsageStats {

FILE: src/types/scaffoldFrontmatter.ts
  type ScaffoldFileType (line 14) | type ScaffoldFileType = 'doc' | 'agent' | 'skill' | 'plan';
  type ScaffoldStatus (line 19) | type ScaffoldStatus = 'unfilled' | 'filled';
  type BaseScaffoldFrontmatter (line 24) | interface BaseScaffoldFrontmatter {
  type DocScaffoldFrontmatter (line 42) | interface DocScaffoldFrontmatter extends BaseScaffoldFrontmatter {
  type AgentScaffoldFrontmatter (line 51) | interface AgentScaffoldFrontmatter extends BaseScaffoldFrontmatter {
  type SkillScaffoldFrontmatter (line 62) | interface SkillScaffoldFrontmatter extends BaseScaffoldFrontmatter {
  type PlanScaffoldFrontmatter (line 77) | interface PlanScaffoldFrontmatter extends BaseScaffoldFrontmatter {
  type ScaffoldFrontmatter (line 94) | type ScaffoldFrontmatter =
  function isDocFrontmatter (line 103) | function isDocFrontmatter(fm: ScaffoldFrontmatter): fm is DocScaffoldFro...
  function isAgentFrontmatter (line 110) | function isAgentFrontmatter(fm: ScaffoldFrontmatter): fm is AgentScaffol...
  function isSkillFrontmatter (line 117) | function isSkillFrontmatter(fm: ScaffoldFrontmatter): fm is SkillScaffol...
  function isPlanFrontmatter (line 124) | function isPlanFrontmatter(fm: ScaffoldFrontmatter): fm is PlanScaffoldF...
  function createDocFrontmatter (line 131) | function createDocFrontmatter(
  function createAgentFrontmatter (line 150) | function createAgentFrontmatter(
  function createSkillFrontmatter (line 171) | function createSkillFrontmatter(
  function createPlanFrontmatter (line 198) | function createPlanFrontmatter(
  function serializeFrontmatter (line 227) | function serializeFrontmatter(fm: ScaffoldFrontmatter): string {

FILE: src/utils/cliUI.ts
  class CLIInterface (line 7) | class CLIInterface {
    method constructor (line 12) | constructor(private readonly translate: TranslateFn) {}
    method displayProjectInfo (line 14) | displayProjectInfo(repoPath: string, outputDir: string, mode: string):...
    method startSpinner (line 23) | startSpinner(text: string): void {
    method updateSpinner (line 35) | updateSpinner(text: string, type?: 'success' | 'fail' | 'warn' | 'info...
    method stopSpinner (line 68) | stopSpinner(success: boolean = true): void {
    method createProgressBar (line 79) | createProgressBar(total: number, title: string): void {
    method updateProgress (line 94) | updateProgress(current: number, task: string): void {
    method completeProgress (line 99) | completeProgress(): void {
    method displayAnalysisResults (line 105) | displayAnalysisResults(totalFiles: number, totalDirs: number, totalSiz...
    method displayFileTypeDistribution (line 115) | displayFileTypeDistribution(distribution: Map<string, number>, totalFi...
    method displayGenerationSummary (line 135) | displayGenerationSummary(docsGenerated: number, agentsGenerated: numbe...
    method displayError (line 153) | displayError(message: string, error?: Error): void {
    method displayInfo (line 165) | displayInfo(title: string, message: string): void {
    method displaySuccess (line 173) | displaySuccess(message: string): void {
    method displayWarning (line 177) | displayWarning(message: string): void {
    method displayStep (line 181) | displayStep(step: number, total: number, description: string): void {
    method formatBytes (line 188) | formatBytes(bytes: number): string {
    method t (line 196) | private t(key: TranslationKey, params?: TranslateParams): string {

FILE: src/utils/fileMapper.ts
  class FileMapper (line 7) | class FileMapper {
    method constructor (line 23) | constructor(customExcludes: string[] = []) {
    method loadGitignorePatterns (line 28) | private async loadGitignorePatterns(repoPath: string): Promise<string[...
    method mapRepository (line 40) | async mapRepository(repoPath: string, includePatterns?: string[]): Pro...
    method readFileContent (line 122) | async readFileContent(filePath: string): Promise<string> {
    method getFilesByExtension (line 130) | getFilesByExtension(files: FileInfo[], extension: string): FileInfo[] {
    method isTextFile (line 134) | isTextFile(filePath: string): boolean {
    method extractTopLevelSegment (line 147) | private extractTopLevelSegment(relativePath: string): string | null {

FILE: src/utils/frontMatter.ts
  type FrontMatter (line 16) | interface FrontMatter {
  type ParsedScaffoldFrontmatter (line 25) | interface ParsedScaffoldFrontmatter {
  function isScaffoldFrontmatter (line 48) | function isScaffoldFrontmatter(fm: FrontMatter | ParsedScaffoldFrontmatt...
  constant FRONT_MATTER_DELIMITER (line 52) | const FRONT_MATTER_DELIMITER = '---';
  function needsFill (line 59) | async function needsFill(filePath: string): Promise<boolean> {
  function readFirstLines (line 88) | async function readFirstLines(filePath: string, n: number): Promise<stri...
  function parseFrontMatter (line 113) | function parseFrontMatter(content: string): { frontMatter: FrontMatter |...
  function addFrontMatter (line 144) | function addFrontMatter(content: string, frontMatter: FrontMatter): stri...
  function removeFrontMatter (line 162) | function removeFrontMatter(content: string): string {
  function hasFrontMatter (line 170) | function hasFrontMatter(content: string): boolean {
  function createUnfilledFrontMatter (line 177) | function createUnfilledFrontMatter(): FrontMatter {
  function getUnfilledFiles (line 187) | async function getUnfilledFiles(contextDir: string): Promise<string[]> {
  function getFilledStats (line 204) | async function getFilledStats(contextDir: string): Promise<{
  function parseScaffoldFrontMatter (line 231) | function parseScaffoldFrontMatter(content: string): {
  function getDocumentName (line 350) | function getDocumentName(content: string): string | null {
  function isScaffoldContent (line 369) | function isScaffoldContent(content: string): boolean {

FILE: src/utils/gitService.ts
  type GitChanges (line 7) | interface GitChanges {
  type GitState (line 14) | interface GitState {
  type CommitResult (line 18) | interface CommitResult {
  class GitService (line 24) | class GitService {
    method constructor (line 28) | constructor(repoPath: string) {
    method isGitRepository (line 33) | isGitRepository(): boolean {
    method getCurrentCommit (line 45) | getCurrentCommit(): string {
    method getChangedFiles (line 56) | getChangedFiles(since?: string): GitChanges {
    method getStagedFiles (line 133) | getStagedFiles(): string[] {
    method getStagedChanges (line 146) | getStagedChanges(): GitChanges {
    method getUncommittedChanges (line 194) | getUncommittedChanges(): GitChanges {
    method getBranchName (line 246) | getBranchName(): string {
    method getLastProcessedCommit (line 257) | getLastProcessedCommit(): string | null {
    method saveState (line 269) | saveState(commit: string): void {
    method getState (line 285) | getState(): GitState | null {
    method clearState (line 296) | clearState(): void {
    method filterRelevantFiles (line 306) | filterRelevantFiles(files: string[], fileMapper: any): string[] {
    method isFileTracked (line 313) | isFileTracked(filePath: string): boolean {
    method getTrackedFiles (line 325) | getTrackedFiles(): string[] {
    method filterTrackedFiles (line 338) | filterTrackedFiles(files: string[]): string[] {
    method getCommitMessage (line 343) | getCommitMessage(commit: string): string {
    method getFileHistory (line 354) | getFileHistory(filePath: string, limit: number = 10): Array<{ commit: ...
    method getAllTrackedFilesAsAdded (line 375) | private getAllTrackedFilesAsAdded(): GitChanges {
    method isValidCommit (line 395) | isValidCommit(commit: string): boolean {
    method getUnstagedFiles (line 410) | getUnstagedFiles(): string[] {
    method stageFiles (line 428) | stageFiles(patterns: string[]): string[] {
    method commit (line 459) | commit(message: string, coAuthor?: string): CommitResult {
    method hasUncommittedChanges (line 498) | hasUncommittedChanges(): boolean {
    method getCommitsBetween (line 511) | getCommitsBetween(fromCommit: string, toCommit: string = 'HEAD'): stri...
    method getCommitInfo (line 524) | getCommitInfo(commit: string): { hash: string; shortHash: string; mess...
    method displayCommitTrackingInfo (line 538) | displayCommitTrackingInfo(verbose: boolean = false): void {
    method hasContextBeenInitialized (line 576) | hasContextBeenInitialized(outputDir: string): boolean {

FILE: src/utils/gitignoreManager.ts
  constant DEFAULT_EXCLUDE_PATTERNS (line 19) | const DEFAULT_EXCLUDE_PATTERNS: readonly string[] = [
  type GitIgnoreManagerOptions (line 30) | interface GitIgnoreManagerOptions {
  class GitIgnoreManager (line 37) | class GitIgnoreManager {
    method constructor (line 42) | constructor(private readonly options: GitIgnoreManagerOptions = {}) {
    method loadFromRepo (line 53) | async loadFromRepo(repoPath: string): Promise<void> {
    method shouldIgnore (line 91) | shouldIgnore(relativePath: string): boolean {
    method filterPaths (line 117) | filterPaths(relativePaths: string[]): string[] {
    method isLoaded (line 124) | get isLoaded(): boolean {
    method clearCache (line 131) | clearCache(): void {
    method parseGitignore (line 139) | private parseGitignore(content: string): string[] {
    method applyDefaults (line 149) | private applyDefaults(): void {
  type EnsureGitignorePatternsOptions (line 156) | interface EnsureGitignorePatternsOptions {
  function normalizeGitignorePattern (line 160) | function normalizeGitignorePattern(pattern: string): string {
  function ensureGitignorePatterns (line 173) | async function ensureGitignorePatterns(

FILE: src/utils/i18n.ts
  type Locale (line 1) | type Locale = 'en' | 'pt-BR';
  constant SUPPORTED_LOCALES (line 3) | const SUPPORTED_LOCALES: Locale[] = ['en', 'pt-BR'];
  constant DEFAULT_LOCALE (line 4) | const DEFAULT_LOCALE: Locale = 'en';
  type TranslationKey (line 551) | type TranslationKey = keyof typeof englishMessages;
  type TranslationDictionary (line 553) | type TranslationDictionary = Record<TranslationKey, string>;
  type TranslateParams (line 1105) | type TranslateParams = Record<string, string | number | undefined>;
  type TranslateFn (line 1107) | type TranslateFn = (key: TranslationKey, params?: TranslateParams) => st...
  function createTranslator (line 1109) | function createTranslator(locale: Locale): TranslateFn {
  function normalizeLocale (line 1119) | function normalizeLocale(locale: string): Locale {
  function detectLocale (line 1123) | function detectLocale(
  function extractLocaleFromArgs (line 1144) | function extractLocaleFromArgs(argv: string[]): string | undefined {
  function fillTemplate (line 1160) | function fillTemplate(template: string, params?: TranslateParams): string {
  function isSupportedLocale (line 1170) | function isSupportedLocale(locale: string): boolean {
  function resolveLocaleCandidate (line 1174) | function resolveLocaleCandidate(locale?: string | null): Locale | undefi...

FILE: src/utils/pathSecurity.ts
  class SecurityError (line 21) | class SecurityError extends Error {
    method constructor (line 25) | constructor(message: string, attemptedPath: string, workspaceRoot: str...
  class PathValidator (line 39) | class PathValidator {
    method constructor (line 42) | constructor(private readonly workspaceRoot: string) {
    method validatePath (line 53) | validatePath(inputPath: string): string {
    method isWithinBoundary (line 91) | isWithinBoundary(resolvedPath: string): boolean {
    method safeResolve (line 102) | safeResolve(inputPath: string): string | null {
    method hasUrlEncodedTraversal (line 113) | private hasUrlEncodedTraversal(input: string): boolean {

FILE: src/utils/processShutdown.ts
  type ShutdownTarget (line 1) | interface ShutdownTarget {
  type ShutdownController (line 5) | interface ShutdownController {
  type ShutdownControllerOptions (line 10) | interface ShutdownControllerOptions {
  function registerProcessShutdown (line 22) | function registerProcessShutdown(

FILE: src/utils/prompts/configSummary.ts
  function displayConfigSummary (line 8) | function displayConfigSummary(summary: ConfigSummary, _t: TranslateFn): ...

FILE: src/utils/prompts/index.ts
  function promptInteractiveMode (line 16) | async function promptInteractiveMode(t: TranslateFn): Promise<Interactiv...
  function promptAnalysisOptions (line 32) | async function promptAnalysisOptions(
  function promptConfirmProceed (line 90) | async function promptConfirmProceed(t: TranslateFn): Promise<boolean> {
  function promptLoadEnv (line 100) | async function promptLoadEnv(t: TranslateFn): Promise<boolean> {

FILE: src/utils/prompts/smartDefaults.ts
  function detectSmartDefaults (line 8) | async function detectSmartDefaults(basePath?: string): Promise<SmartDefa...
  function detectProjectLanguages (line 29) | async function detectProjectLanguages(repoPath: string): Promise<string[...

FILE: src/utils/prompts/types.ts
  type InteractiveMode (line 1) | type InteractiveMode = 'quick' | 'advanced';
  type PathsPromptResult (line 3) | interface PathsPromptResult {
  type SmartDefaults (line 8) | interface SmartDefaults {
  type ConfigSummary (line 15) | interface ConfigSummary {
  type AnalysisOptions (line 25) | interface AnalysisOptions {

FILE: src/utils/splashScreen.test.ts
  function stripAnsi (line 10) | function stripAnsi(value: string): string {

FILE: src/utils/splashScreen.ts
  type SplashScreenLine (line 7) | interface SplashScreenLine {
  type SplashScreenOptions (line 13) | interface SplashScreenOptions {
  function renderSplashScreen (line 19) | function renderSplashScreen(options: SplashScreenOptions): string {
  function packageNameToDisplayName (line 41) | function packageNameToDisplayName(packageName: string): string {
  function formatSplashDirectory (line 57) | function formatSplashDirectory(directory: string, maxLength = 48): string {
  function formatLine (line 69) | function formatLine(line: SplashScreenLine, labelWidth: number): string {
  function truncateMiddle (line 80) | function truncateMiddle(value: string, maxLength: number): string {

FILE: src/utils/themedPrompt.ts
  type Choice (line 9) | type Choice<V> = {
  function themedSelect (line 18) | async function themedSelect<V>(config: {
  function themedConfirm (line 31) | async function themedConfirm(config: {
  function themedInput (line 41) | async function themedInput(config: {
  function themedPassword (line 52) | async function themedPassword(config: {
  function themedCheckbox (line 62) | async function themedCheckbox<V>(config: {

FILE: src/utils/versionChecker.ts
  type VersionCheckOptions (line 6) | interface VersionCheckOptions {
  constant DEFAULT_TIMEOUT_MS (line 17) | const DEFAULT_TIMEOUT_MS = 2000;
  constant DISABLE_ENV_FLAGS (line 19) | const DISABLE_ENV_FLAGS = ['DOTCONTEXT_DISABLE_UPDATE_CHECK', 'NO_UPDATE...
  function fetchLatestVersion (line 21) | async function fetchLatestVersion(packageName: string, timeoutMs: number...
  function checkForUpdates (line 45) | async function checkForUpdates(options: VersionCheckOptions): Promise<vo...

FILE: src/version.ts
  constant VERSION (line 15) | const VERSION: string = pkg.version;
  constant PACKAGE_NAME (line 16) | const PACKAGE_NAME: string = pkg.name;

FILE: src/workflow/agents/agentRegistry.ts
  constant BUILT_IN_AGENTS (line 14) | const BUILT_IN_AGENTS = [
  type BuiltInAgentType (line 31) | type BuiltInAgentType = (typeof BUILT_IN_AGENTS)[number];
  type AgentMetadata (line 36) | interface AgentMetadata {
  type DiscoveredAgents (line 48) | interface DiscoveredAgents {
  function isBuiltInAgent (line 57) | function isBuiltInAgent(agentType: string): agentType is BuiltInAgentType {
  class AgentRegistry (line 67) | class AgentRegistry {
    method constructor (line 71) | constructor(repoPath: string) {
    method discoverAll (line 78) | async discoverAll(): Promise<DiscoveredAgents> {
    method discoverBuiltIn (line 92) | async discoverBuiltIn(): Promise<AgentMetadata[]> {
    method discoverCustom (line 106) | async discoverCustom(): Promise<AgentMetadata[]> {
    method getAgentMetadata (line 137) | async getAgentMetadata(agentType: string): Promise<AgentMetadata> {
    method agentExists (line 171) | async agentExists(agentType: string): Promise<boolean> {
    method getPlaybookContent (line 179) | async getPlaybookContent(agentType: string): Promise<string | null> {
    method clearCache (line 192) | clearCache(): void {
    method extractMetadataFromFile (line 199) | private async extractMetadataFromFile(
  function createAgentRegistry (line 220) | function createAgentRegistry(repoPath: string): AgentRegistry {

FILE: src/workflow/collaboration.ts
  function generateSessionId (line 20) | function generateSessionId(): string {
  class CollaborationSession (line 29) | class CollaborationSession {
    method constructor (line 37) | constructor(topic: string, participants?: PrevcRole[]) {
    method getId (line 49) | getId(): string {
    method start (line 56) | async start(
    method getStatus (line 72) | getStatus(): CollaborationStatus {
    method contribute (line 85) | contribute(role: PrevcRole, message: string): void {
    method getContributions (line 106) | getContributions(): Contribution[] {
    method getContributionsByRole (line 113) | getContributionsByRole(role: PrevcRole): Contribution[] {
    method synthesize (line 120) | async synthesize(): Promise<CollaborationSynthesis> {
    method extractDecisions (line 140) | private async extractDecisions(): Promise<string[]> {
    method generateRecommendations (line 175) | private async generateRecommendations(): Promise<string[]> {
    method selectRelevantRoles (line 219) | private async selectRelevantRoles(topic: string): Promise<PrevcRole[]> {
    method getDurationMinutes (line 283) | getDurationMinutes(): number {
    method getParticipantNames (line 292) | getParticipantNames(): string[] {
    method isParticipant (line 299) | isParticipant(role: PrevcRole): boolean {
    method addParticipant (line 306) | addParticipant(role: PrevcRole): void {
    method removeParticipant (line 315) | removeParticipant(role: PrevcRole): void {
  class CollaborationManager (line 325) | class CollaborationManager {
    method createSession (line 331) | createSession(topic: string, participants?: PrevcRole[]): Collaboratio...
    method getSession (line 340) | getSession(id: string): CollaborationSession | undefined {
    method getActiveSessions (line 347) | getActiveSessions(): CollaborationSession[] {
    method endSession (line 356) | async endSession(id: string): Promise<CollaborationSynthesis | null> {
    method clearConcludedSessions (line 369) | clearConcludedSessions(): void {

FILE: src/workflow/errors.ts
  class WorkflowError (line 12) | class WorkflowError extends Error {
    method constructor (line 13) | constructor(message: string) {
  class WorkflowGateError (line 22) | class WorkflowGateError extends WorkflowError {
    method constructor (line 30) | constructor(options: {
  class NoPlanToApproveError (line 47) | class NoPlanToApproveError extends WorkflowError {
    method constructor (line 48) | constructor(message = 'No plan is linked to approve. Link a plan first...
  class NoWorkflowError (line 57) | class NoWorkflowError extends WorkflowError {
    method constructor (line 58) | constructor(message = 'No workflow found. Run workflowInit first.') {

FILE: src/workflow/gates/gateChecker.test.ts
  function createMockStatus (line 9) | function createMockStatus(overrides: Partial<PrevcStatus> = {}): PrevcSt...

FILE: src/workflow/gates/gateChecker.ts
  type GateStatus (line 19) | interface GateStatus {
  type GateCheckResult (line 29) | interface GateCheckResult {
  function getDefaultSettings (line 45) | function getDefaultSettings(scale: ProjectScale | string): WorkflowSetti...
  class WorkflowGateChecker (line 77) | class WorkflowGateChecker {
    method checkGates (line 81) | checkGates(
    method enforceGates (line 171) | enforceGates(
    method getEffectiveSettings (line 197) | private getEffectiveSettings(status: PrevcStatus): WorkflowSettings {
    method hasLinkedPlan (line 215) | private hasLinkedPlan(status: PrevcStatus): boolean {
    method isPlanApproved (line 237) | private isPlanApproved(status: PrevcStatus): boolean {
    method getNextPhase (line 244) | private getNextPhase(current: PrevcPhase): PrevcPhase | null {
  function createGateChecker (line 252) | function createGateChecker(): WorkflowGateChecker {

FILE: src/workflow/orchestration/agentOrchestrator.ts
  constant AGENT_TYPES (line 14) | const AGENT_TYPES = [
  type AgentType (line 31) | type AgentType = (typeof AGENT_TYPES)[number];
  constant PHASE_TO_AGENTS (line 36) | const PHASE_TO_AGENTS: Record<PrevcPhase, AgentType[]> = {
  constant ROLE_TO_AGENTS (line 59) | const ROLE_TO_AGENTS: Record<PrevcRole, AgentType[]> = {
  constant TASK_KEYWORDS (line 86) | const TASK_KEYWORDS: Record<string, AgentType[]> = {
  class AgentOrchestrator (line 168) | class AgentOrchestrator {
    method getAgentsForPhase (line 172) | getAgentsForPhase(phase: PrevcPhase): AgentType[] {
    method getAgentsForRole (line 179) | getAgentsForRole(role: PrevcRole): AgentType[] {
    method getPrimaryAgentForRole (line 186) | getPrimaryAgentForRole(role: PrevcRole): AgentType | null {
    method selectAgentsByTask (line 194) | selectAgentsByTask(taskDescription: string): AgentType[] {
    method getAgentHandoffSequence (line 216) | getAgentHandoffSequence(phases: PrevcPhase[]): AgentType[] {
    method getTaskAgentSequence (line 236) | getTaskAgentSequence(
    method specialistToAgent (line 264) | specialistToAgent(specialist: string): AgentType | null {
    method getAllAgentTypes (line 284) | getAllAgentTypes(): AgentType[] {
    method isValidAgentType (line 291) | isValidAgentType(type: string): type is AgentType {
    method getAgentDescription (line 298) | getAgentDescription(agent: AgentType): string {

FILE: src/workflow/orchestration/documentLinker.ts
  type DocType (line 14) | type DocType =
  type DocGuide (line 29) | interface DocGuide {
  constant DOCUMENT_GUIDES (line 39) | const DOCUMENT_GUIDES: DocGuide[] = [
  constant AGENT_TO_DOCS (line 105) | const AGENT_TO_DOCS: Record<AgentType, DocType[]> = {
  constant PHASE_TO_DOCS (line 125) | const PHASE_TO_DOCS: Record<PrevcPhase, DocType[]> = {
  constant ROLE_TO_DOCS (line 136) | const ROLE_TO_DOCS: Record<PrevcRole, DocType[]> = {
  class DocumentLinker (line 150) | class DocumentLinker {
    method getDocsForAgent (line 154) | getDocsForAgent(agent: AgentType): DocGuide[] {
    method getDocsForPhase (line 162) | getDocsForPhase(phase: PrevcPhase): DocGuide[] {
    method getDocsForRole (line 170) | getDocsForRole(role: PrevcRole): DocGuide[] {
    method getPrimaryDocForAgent (line 178) | getPrimaryDocForAgent(agent: AgentType): DocGuide | null {
    method getAllDocs (line 186) | getAllDocs(): DocGuide[] {
    method getDocByType (line 193) | getDocByType(type: DocType): DocGuide | null {
    method getDocPathsForAgent (line 200) | getDocPathsForAgent(agent: AgentType): string[] {
    method getDocPathsForPhase (line 207) | getDocPathsForPhase(phase: PrevcPhase): string[] {
    method getDocPathsForRole (line 214) | getDocPathsForRole(role: PrevcRole): string[] {
    method getDocsForAgents (line 221) | getDocsForAgents(agents: AgentType[]): DocGuide[] {
    method getDocsForTask (line 235) | getDocsForTask(taskDescription: string): DocGuide[] {
    method generateAgentDocLinks (line 277) | generateAgentDocLinks(agent: AgentType): string {
    method generatePhaseDocLinks (line 291) | generatePhaseDocLinks(phase: PrevcPhase): string {
    method getGuidesByTypes (line 305) | private getGuidesByTypes(types: DocType[]): DocGuide[] {

FILE: src/workflow/orchestrator.ts
  type CompletePhaseOptions (line 32) | interface CompletePhaseOptions {
  type InitWorkflowOptions (line 40) | interface InitWorkflowOptions {
  class PrevcOrchestrator (line 52) | class PrevcOrchestrator {
    method constructor (line 59) | constructor(contextPath: string) {
    method hasWorkflow (line 71) | async hasWorkflow(): Promise<boolean> {
    method initWorkflow (line 78) | async initWorkflow(context: ProjectContext): Promise<PrevcStatus> {
    method initWorkflowWithScale (line 98) | async initWorkflowWithScale(
    method resetWorkflow (line 138) | async resetWorkflow(archive: boolean): Promise<void> {
    method archiveCurrentWorkflow (line 151) | private async archiveCurrentWorkflow(): Promise<void> {
    method initWorkflowWithOptions (line 170) | async initWorkflowWithOptions(options: InitWorkflowOptions): Promise<P...
    method getStatus (line 177) | async getStatus(): Promise<PrevcStatus> {
    method getCurrentPhase (line 184) | async getCurrentPhase(): Promise<PrevcPhase> {
    method getCurrentRole (line 191) | async getCurrentRole(): Promise<PrevcRole | null> {
    method getCurrentPhaseDefinition (line 198) | async getCurrentPhaseDefinition() {
    method handoff (line 209) | async handoff(
    method getNextAgentSuggestion (line 229) | getNextAgentSuggestion(currentAgent: string): { agent: string; reason:...
    method getPhaseOrchestration (line 249) | async getPhaseOrchestration(phase: PrevcPhase): Promise<PhaseOrchestra...
    method getAgentDefaultTask (line 291) | private getAgentDefaultTask(agent: string): string {
    method buildToolGuidance (line 315) | private buildToolGuidance(phase: PrevcPhase, startAgent: string): Tool...
    method buildOrchestrationSteps (line 326) | private buildOrchestrationSteps(phase: PrevcPhase, agents: string[]): ...
    method buildOrchestrationInstruction (line 343) | private buildOrchestrationInstruction(phase: PrevcPhase, startAgent: s...
    method completePhase (line 368) | async completePhase(
    method checkGates (line 407) | async checkGates(): Promise<GateCheckResult> {
    method setSettings (line 415) | async setSettings(settings: Partial<WorkflowSettings>): Promise<Workfl...
    method getSettings (line 422) | async getSettings(): Promise<WorkflowSettings> {
    method markPlanCreated (line 429) | async markPlanCreated(planSlug: string): Promise<void> {
    method approvePlan (line 436) | async approvePlan(approver: PrevcRole | string, notes?: string): Promi...
    method getApproval (line 443) | async getApproval(): Promise<PlanApproval | undefined> {
    method advanceToNextPhase (line 450) | async advanceToNextPhase(): Promise<PrevcPhase | null> {
    method getNextPhase (line 461) | async getNextPhase(): Promise<PrevcPhase | null> {
    method isComplete (line 468) | async isComplete(): Promise<boolean> {
    method getRecommendedActions (line 475) | async getRecommendedActions(): Promise<string[]> {
    method getSummary (line 507) | async getSummary(): Promise<WorkflowSummary> {
    method updateCurrentTask (line 541) | async updateCurrentTask(task: string): Promise<void> {
    method startRole (line 554) | async startRole(role: PrevcRole): Promise<void> {
    method completeRole (line 570) | async completeRole(role: PrevcRole, outputs: string[]): Promise<void> {
  type WorkflowSummary (line 582) | interface WorkflowSummary {

FILE: src/workflow/phases.ts
  constant PREVC_PHASE_ORDER (line 17) | const PREVC_PHASE_ORDER: PrevcPhase[] = ['P', 'R', 'E', 'V', 'C'];
  constant PREVC_PHASES (line 22) | const PREVC_PHASES: Record<PrevcPhase, PhaseDefinition> = {
  constant PHASE_NAMES (line 68) | const PHASE_NAMES: Record<PrevcPhase, string> = {
  constant PHASE_NAMES_EN (line 79) | const PHASE_NAMES_EN = PHASE_NAMES;
  constant PHASE_NAMES_PT (line 84) | const PHASE_NAMES_PT: Record<PrevcPhase, string> = {
  function getPhaseDefinition (line 95) | function getPhaseDefinition(phase: PrevcPhase): PhaseDefinition {
  function getNextPhase (line 102) | function getNextPhase(currentPhase: PrevcPhase): PrevcPhase | null {
  function getPreviousPhase (line 113) | function getPreviousPhase(currentPhase: PrevcPhase): PrevcPhase | null {
  function isPhaseOptional (line 124) | function isPhaseOptional(phase: PrevcPhase): boolean {
  function getRolesForPhase (line 131) | function getRolesForPhase(phase: PrevcPhase): string[] {
  function getOutputsForPhase (line 138) | function getOutputsForPhase(phase: PrevcPhase): string[] {
  function isValidPhase (line 145) | function isValidPhase(phase: string): phase is PrevcPhase {
  function getPhaseOrder (line 152) | function getPhaseOrder(phase: PrevcPhase): number {

FILE: src/workflow/plans/planLinker.ts
  class PlanLinker (line 37) | class PlanLinker {
    method constructor (line 46) | constructor(repoPath: string, statusManager?: PrevcStatusManager, auto...
    method create (line 59) | static async create(
    method ensureWorkflowPlanIndex (line 70) | async ensureWorkflowPlanIndex(): Promise<void> {
    method discoverAgents (line 86) | async discoverAgents(): Promise<Array<{ type: string; path: string; is...
    method getAgentInfo (line 99) | async getAgentInfo(agentType: string): Promise<AgentMetadata> {
    method linkPlan (line 106) | async linkPlan(planSlug: string): Promise<PlanReference | null> {
    method getLinkedPlans (line 134) | async getLinkedPlans(): Promise<WorkflowPlans> {
    method updatePlanReference (line 152) | async updatePlanReference(
    method getLinkedPlan (line 183) | async getLinkedPlan(planSlug: string): Promise<LinkedPlan | null> {
    method getPlansForPhase (line 203) | async getPlansForPhase(phase: PrevcPhase): Promise<LinkedPlan[]> {
    method updatePlanPhase (line 223) | async updatePlanPhase(
    method recordDecision (line 280) | async recordDecision(
    method getPhaseMappingForWorkflow (line 328) | getPhaseMappingForWorkflow(plan: LinkedPlan, currentPrevcPhase: PrevcP...
    method hasPendingWorkForPhase (line 335) | hasPendingWorkForPhase(plan: LinkedPlan, phase: PrevcPhase): boolean {
    method getPlanProgress (line 343) | async getPlanProgress(planSlug: string): Promise<{
    method updatePlanStep (line 382) | async updatePlanStep(
    method updatePlanApproval (line 501) | async updatePlanApproval(
    method getPlanExecutionStatus (line 558) | async getPlanExecutionStatus(planSlug: string): Promise<PlanExecutionT...
    method syncPlanMarkdown (line 566) | async syncPlanMarkdown(planSlug: string): Promise<boolean> {
    method recordPhaseCommit (line 592) | async recordPhaseCommit(
    method loadPlanTracking (line 638) | private async loadPlanTracking(planSlug: string): Promise<PlanExecutio...
    method calculateStepProgress (line 682) | private calculateStepProgress(tracking: PlanExecutionTracking): number {
    method updateFrontmatterProgress (line 697) | private updateFrontmatterProgress(content: string, tracking: PlanExecu...
    method updateStepCheckboxes (line 736) | private updateStepCheckboxes(content: string, tracking: PlanExecutionT...
    method updateExecutionHistorySection (line 789) | private updateExecutionHistorySection(content: string, tracking: PlanE...
    method generateExecutionHistoryMarkdown (line 833) | private generateExecutionHistoryMarkdown(tracking: PlanExecutionTracki...
    method parsePlanFile (line 892) | private parsePlanFile(content: string, slug: string): { title: string;...
    method parseFrontMatter (line 905) | private parseFrontMatter(content: string): {
    method parsePlanToLinked (line 1003) | private parsePlanToLinked(content: string, ref: PlanReference): Linked...
    method extractPhasesFromBody (line 1049) | private extractPhasesFromBody(content: string): PlanPhase[] {
    method extractDecisions (line 1096) | private extractDecisions(): PlanDecision[] {
    method extractAgentsFromBody (line 1104) | private extractAgentsFromBody(content: string): string[] {
    method extractDocsFromBody (line 1124) | private extractDocsFromBody(content: string): string[] {
    method addPlanToWorkflow (line 1144) | private async addPlanToWorkflow(ref: PlanReference): Promise<void> {
    method clearAllPlans (line 1188) | async clearAllPlans(): Promise<void> {
    method archivePlans (line 1207) | async archivePlans(): Promise<void> {
    method autoCommitPhase (line 1242) | private async autoCommitPhase(planSlug: string, phaseId: string): Prom...
  function createPlanLinker (line 1308) | function createPlanLinker(repoPath: string, statusManager?: PrevcStatusM...

FILE: src/workflow/plans/types.ts
  constant PLAN_PHASE_TO_PREVC (line 13) | const PLAN_PHASE_TO_PREVC: Record<string, PrevcPhase> = {
  type PlanReference (line 29) | interface PlanReference {
  type PlanStep (line 53) | interface PlanStep {
  type PlanPhase (line 71) | interface PlanPhase {
  type PlanDecision (line 93) | interface PlanDecision {
  type PlanRisk (line 117) | interface PlanRisk {
  type AgentLineupEntry (line 137) | interface AgentLineupEntry {
  type LinkedPlan (line 147) | interface LinkedPlan {
  type WorkflowPlans (line 171) | interface WorkflowPlans {
  type PlanSyncEvent (line 183) | interface PlanSyncEvent {
  type StepExecution (line 199) | interface StepExecution {
  type PlanPhaseTracking (line 219) | interface PlanPhaseTracking {
  type PlanExecutionTracking (line 244) | interface PlanExecutionTracking {

FILE: src/workflow/prevcConfig.ts
  constant ROLE_CONFIG (line 12) | const ROLE_CONFIG: Record<PrevcRole, RoleDefinition> = {
  function getRoleConfig (line 129) | function getRoleConfig(role: PrevcRole): RoleDefinition {
  function getRolesForPhase (line 136) | function getRolesForPhase(phase: string): PrevcRole[] {
  function getOutputsForRole (line 150) | function getOutputsForRole(role: PrevcRole): string[] {
  function getResponsibilitiesForRole (line 157) | function getResponsibilitiesForRole(role: PrevcRole): string[] {

FILE: src/workflow/roles.ts
  constant PREVC_ROLES (line 13) | const PREVC_ROLES = [
  constant ROLE_TO_SPECIALISTS (line 29) | const ROLE_TO_SPECIALISTS: Record<PrevcRole, string[]> = {
  constant SPECIALIST_TO_ROLE (line 51) | const SPECIALIST_TO_ROLE: Record<string, PrevcRole> = {
  constant ROLE_DISPLAY_NAMES (line 71) | const ROLE_DISPLAY_NAMES: Record<PrevcRole, string> = {
  constant ROLE_DISPLAY_NAMES_EN (line 85) | const ROLE_DISPLAY_NAMES_EN = ROLE_DISPLAY_NAMES;
  constant ROLE_DISPLAY_NAMES_PT (line 90) | const ROLE_DISPLAY_NAMES_PT: Record<PrevcRole, string> = {
  function isValidRole (line 104) | function isValidRole(role: string): role is PrevcRole {
  function getRoleForSpecialist (line 112) | function getRoleForSpecialist(specialist: string): PrevcRole | null {
  function getSpecialistsForRole (line 120) | function getSpecialistsForRole(role: PrevcRole): string[] {

FILE: src/workflow/scaling.ts
  constant SCALE_ROUTES (line 13) | const SCALE_ROUTES: Record<ProjectScale, ScaleRoute> = {
  constant BUG_FIX_KEYWORDS (line 40) | const BUG_FIX_KEYWORDS = [
  constant SIMPLE_FEATURE_KEYWORDS (line 55) | const SIMPLE_FEATURE_KEYWORDS = [
  constant SECURITY_KEYWORDS (line 70) | const SECURITY_KEYWORDS = [
  constant DOCUMENTATION_KEYWORDS (line 86) | const DOCUMENTATION_KEYWORDS = [
  function isBugFix (line 100) | function isBugFix(description: string): boolean {
  function isSimpleFeature (line 108) | function isSimpleFeature(description: string): boolean {
  function requiresSecurityAudit (line 116) | function requiresSecurityAudit(description: string): boolean {
  function requiresDocumentation (line 124) | function requiresDocumentation(description: string): boolean {
  function detectProjectScale (line 132) | function detectProjectScale(context: ProjectContext): ProjectScale {
  function getScaleRoute (line 163) | function getScaleRoute(scale: ProjectScale): ScaleRoute {
  function getPhasesForScale (line 170) | function getPhasesForScale(scale: ProjectScale): PrevcPhase[] {
  function getRolesForScale (line 177) | function getRolesForScale(scale: ProjectScale): PrevcRole[] | 'all' {
  function isPhaseRequiredForScale (line 184) | function isPhaseRequiredForScale(
  function getScaleName (line 194) | function getScaleName(scale: ProjectScale): string {
  function getScaleFromName (line 208) | function getScaleFromName(name: string): ProjectScale | null {
  function getEstimatedTime (line 222) | function getEstimatedTime(scale: ProjectScale): string {

FILE: src/workflow/skills/frontmatter.ts
  function generateFrontmatter (line 14) | function generateFrontmatter(metadata: SkillMetadata, slug?: string): st...
  function generatePortableFrontmatter (line 41) | function generatePortableFrontmatter(name: string, description: string):...
  function wrapWithFrontmatter (line 48) | function wrapWithFrontmatter(metadata: SkillMetadata, content: string, s...
  function wrapWithPortableFrontmatter (line 56) | function wrapWithPortableFrontmatter(name: string, description: string, ...
  function parseFrontmatter (line 64) | function parseFrontmatter(content: string): { metadata: SkillMetadata; b...
  function stripQuotes (line 117) | function stripQuotes(value: string): string {
  function parsePhaseArray (line 124) | function parsePhaseArray(value: string): PrevcPhase[] {

FILE: src/workflow/skills/skillRegistry.ts
  constant SKILLS_DIR (line 24) | const SKILLS_DIR = '.context/skills';
  constant AGENTS_SKILLS_DIR (line 27) | const AGENTS_SKILLS_DIR = '.agents/skills';
  class SkillRegistry (line 29) | class SkillRegistry {
    method constructor (line 34) | constructor(repoPath: string) {
    method discoverAll (line 42) | async discoverAll(): Promise<DiscoveredSkills> {
    method getSkillMetadata (line 62) | async getSkillMetadata(slug: string): Promise<Skill | null> {
    method getSkillContent (line 70) | async getSkillContent(slug: string): Promise<string | null> {
    method getSkillsForPhase (line 89) | async getSkillsForPhase(phase: PrevcPhase): Promise<Skill[]> {
    method clearCache (line 97) | clearCache(): void {
    method discoverBuiltInSkills (line 104) | private discoverBuiltInSkills(): Skill[] {
    method discoverCustomSkills (line 132) | private discoverCustomSkills(): Skill[] {
    method discoverSkillsFromDirectory (line 149) | private discoverSkillsFromDirectory(
    method parseSkillFile (line 188) | private parseSkillFile(skillPath: string, slug: string, isBuiltIn: boo...
    method discoverResources (line 218) | private discoverResources(skillDir: string): string[] {
    method discoverResourcesRecursive (line 242) | private discoverResourcesRecursive(dir: string): string[] {
    method createBuiltInSkill (line 266) | private createBuiltInSkill(
  function createSkillRegistry (line 290) | function createSkillRegistry(repoPath: string): SkillRegistry {

FILE: src/workflow/skills/skillTemplates.ts
  type SkillTemplate (line 29) | interface SkillTemplate {
  function contentToMarkdown (line 34) | function contentToMarkdown(title: string, overview: string, content: Ski...
  function extractTriggerBullets (line 53) | function extractTriggerBullets(whenToUse?: string): string[] {
  function joinNaturalLanguage (line 66) | function joinNaturalLanguage(items: string[]): string {
  function buildTemplateDescription (line 79) | function buildTemplateDescription(baseDescription: string, content: Skil...
  function getBuiltInSkillTemplates (line 91) | function getBuiltInSkillTemplates(): Record<BuiltInSkillType, SkillTempl...
  function createCommitMessageSkill (line 106) | function createCommitMessageSkill(): SkillTemplate {
  function createPrReviewSkill (line 114) | function createPrReviewSkill(): SkillTemplate {
  function createCodeReviewSkill (line 122) | function createCodeReviewSkill(): SkillTemplate {
  function createTestGenerationSkill (line 130) | function createTestGenerationSkill(): SkillTemplate {
  function createDocumentationSkill (line 138) | function createDocumentationSkill(): SkillTemplate {
  function createRefactoringSkill (line 146) | function createRefactoringSkill(): SkillTemplate {
  function createBugInvestigationSkill (line 154) | function createBugInvestigationSkill(): SkillTemplate {
  function createFeatureBreakdownSkill (line 162) | function createFeatureBreakdownSkill(): SkillTemplate {
  function createApiDesignSkill (line 170) | function createApiDesignSkill(): SkillTemplate {
  function createSecurityAuditSkill (line 178) | function createSecurityAuditSkill(): SkillTemplate {

FILE: src/workflow/skills/types.ts
  type SkillMetadata (line 14) | interface SkillMetadata {
  type Skill (line 30) | interface Skill {
  type SkillReference (line 48) | interface SkillReference {
  type DiscoveredSkills (line 59) | interface DiscoveredSkills {
  constant BUILT_IN_SKILLS (line 68) | const BUILT_IN_SKILLS = [
  type BuiltInSkillType (line 81) | type BuiltInSkillType = (typeof BUILT_IN_SKILLS)[number];
  function isBuiltInSkill (line 86) | function isBuiltInSkill(skillType: string): skillType is BuiltInSkillType {
  constant SKILL_TO_PHASES (line 93) | const SKILL_TO_PHASES: Record<BuiltInSkillType, PrevcPhase[]> = {

FILE: src/workflow/status/statusManager.ts
  class PrevcStatusManager (line 38) | class PrevcStatusManager {
    method constructor (line 43) | constructor(contextPath: string) {
    method legacyStatusPath (line 48) | private get legacyStatusPath(): string {
    method exists (line 55) | async exists(): Promise<boolean> {
    method load (line 62) | async load(): Promise<PrevcStatus> {
    method loadSync (line 90) | loadSync(): PrevcStatus {
    method save (line 118) | async save(status: PrevcStatus): Promise<void> {
    method remove (line 123) | async remove(): Promise<void> {
    method archive (line 131) | async archive(name: string): Promise<void> {
    method persistCanonical (line 143) | private async persistCanonical(status: PrevcStatus): Promise<void> {
    method create (line 153) | async create(options: {
    method updatePhase (line 177) | async updatePhase(phase: PrevcPhase, update: PhaseUpdate): Promise<voi...
    method updateRole (line 192) | async updateRole(role: PrevcRole, update: RoleUpdate): Promise<void> {
    method updateAgent (line 210) | async updateAgent(agentName: string, update: AgentUpdate): Promise<voi...
    method transitionToPhase (line 245) | async transitionToPhase(phase: PrevcPhase): Promise<void> {
    method markPhaseComplete (line 281) | async markPhaseComplete(
    method getCurrentPhase (line 322) | async getCurrentPhase(): Promise<PrevcPhase> {
    method getActiveRole (line 330) | async getActiveRole(): Promise<PrevcRole | null> {
    method getNextPhase (line 345) | async getNextPhase(): Promise<PrevcPhase | null> {
    method isComplete (line 364) | async isComplete(): Promise<boolean> {
    method setSettings (line 383) | async setSettings(settings: Partial<WorkflowSettings>): Promise<Workfl...
    method getSettings (line 402) | async getSettings(): Promise<WorkflowSettings> {
    method markPlanCreated (line 411) | async markPlanCreated(planSlug: string): Promise<void> {
    method approvePlan (line 448) | async approvePlan(approver: PrevcRole | string, notes?: string): Promi...
    method getApproval (line 490) | async getApproval(): Promise<PlanApproval | undefined> {
    method addHistoryEntry (line 498) | async addHistoryEntry(entry: Omit<ExecutionHistoryEntry, 'timestamp'>)...
    method addStepHistoryEntry (line 526) | async addStepHistoryEntry(entry: {
    method getExecutionHistory (line 573) | async getExecutionHistory(): Promise<ExecutionHistory | undefined> {
    method migrateStatus (line 585) | private migrateStatus(status: PrevcStatus): PrevcStatus {
    method parseYaml (line 673) | private parseYaml(content: string): PrevcStatus {
    method serializeYaml (line 886) | private serializeYaml(status: PrevcStatus): string {

FILE: src/workflow/status/templates.ts
  constant PHASE_NAMES (line 21) | const PHASE_NAMES: Record<PrevcPhase, string> = {
  type StepContext (line 32) | interface StepContext {
  function generateResumeContext (line 41) | function generateResumeContext(
  type CreateStatusOptions (line 87) | interface CreateStatusOptions {
  function createInitialStatus (line 97) | function createInitialStatus(options: CreateStatusOptions): PrevcStatus {
  function createQuickFlowStatus (line 156) | function createQuickFlowStatus(name: string): PrevcStatus {
  function createSmallProjectStatus (line 168) | function createSmallProjectStatus(name: string): PrevcStatus {
  function createMediumProjectStatus (line 180) | function createMediumProjectStatus(name: string): PrevcStatus {
  function createLargeProjectStatus (line 192) | function createLargeProjectStatus(name: string): PrevcStatus {

FILE: src/workflow/types.ts
  type PrevcPhase (line 15) | type PrevcPhase = 'P' | 'R' | 'E' | 'V' | 'C';
  type PrevcRole (line 20) | type PrevcRole =
  type ProjectScale (line 33) | enum ProjectScale {
  type StatusType (line 43) | type StatusType = 'pending' | 'in_progress' | 'completed' | 'skipped';
  type PhaseDefinition (line 48) | interface PhaseDefinition {
  type RoleDefinition (line 60) | interface RoleDefinition {
  type ScaleRoute (line 70) | interface ScaleRoute {
  type PhaseStatus (line 81) | interface PhaseStatus {
  type OutputStatus (line 94) | interface OutputStatus {
  type RoleStatus (line 103) | interface RoleStatus {
  type AgentStatus (line 114) | interface AgentStatus {
  type WorkflowPlanRef (line 124) | interface WorkflowPlanRef {
  type WorkflowSettings (line 133) | interface WorkflowSettings {
  type GateType (line 145) | type GateType = 'plan_required' | 'approval_required';
  type PlanApproval (line 150) | interface PlanApproval {
  type ExecutionAction (line 166) | type ExecutionAction =
  type ExecutionHistoryEntry (line 184) | interface ExecutionHistoryEntry {
  type ExecutionHistory (line 207) | interface ExecutionHistory {
  type ProjectMetadata (line 216) | interface ProjectMetadata {
  type PrevcStatus (line 232) | interface PrevcStatus {
  type ProjectContext (line 248) | interface ProjectContext {
  type PhaseUpdate (line 259) | interface PhaseUpdate {
  type RoleUpdate (line 270) | interface RoleUpdate {
  type AgentUpdate (line 281) | interface AgentUpdate {
  type Contribution (line 289) | interface Contribution {
  type CollaborationStatus (line 298) | interface CollaborationStatus {
  type CollaborationSynthesis (line 309) | interface CollaborationSynthesis {
  type AgentSequenceStep (line 320) | interface AgentSequenceStep {
  type SkillSuggestion (line 328) | interface SkillSuggestion {
  type ToolGuidance (line 339) | interface ToolGuidance {
  type PhaseOrchestration (line 351) | interface PhaseOrchestration {
Condensed preview — 310 files, each showing path, character count, and a content snippet. Download the .json file or copy for the full structured content (2,095K chars).
[
  {
    "path": ".context/agents/README.md",
    "chars": 2599,
    "preview": "# Agent Handbook\n\nThis directory contains ready-to-customize playbooks for AI agents collaborating on the current dotcon"
  },
  {
    "path": ".context/agents/bug-fixer.md",
    "chars": 5627,
    "preview": "---\ntype: agent\nname: bug-fixer\ndescription: Analyze bug reports and error messages\nrole: developer\ngenerated: 2026-03-1"
  },
  {
    "path": ".context/agents/code-reviewer.md",
    "chars": 6305,
    "preview": "---\ntype: agent\nname: code-reviewer\ndescription: Review code changes for quality, style, and best practices\nrole: review"
  },
  {
    "path": ".context/agents/documentation-writer.md",
    "chars": 6629,
    "preview": "---\ntype: agent\nname: documentation-writer\ndescription: Create clear, comprehensive documentation\nrole: documenter\ngener"
  },
  {
    "path": ".context/agents/feature-developer.md",
    "chars": 6584,
    "preview": "---\ntype: agent\nname: feature-developer\ndescription: Implement new features according to specifications\nrole: developer\n"
  },
  {
    "path": ".context/agents/performance-optimizer.md",
    "chars": 6611,
    "preview": "---\ntype: agent\nname: performance-optimizer\ndescription: Identify performance bottlenecks\nrole: developer\ngenerated: 202"
  },
  {
    "path": ".context/agents/refactoring-specialist.md",
    "chars": 6832,
    "preview": "---\ntype: agent\nname: refactoring-specialist\ndescription: Identify code smells and improvement opportunities\nrole: devel"
  },
  {
    "path": ".context/agents/test-writer.md",
    "chars": 7530,
    "preview": "---\ntype: agent\nname: test-writer\ndescription: Write comprehensive unit and integration tests\nrole: qa\ngenerated: 2026-0"
  },
  {
    "path": ".context/docs/README.md",
    "chars": 1752,
    "preview": "# Documentation Index\n\nWelcome to the `@dotcontext/cli` repository knowledge base. Start with the project overview, then"
  },
  {
    "path": ".context/docs/codebase-map.json",
    "chars": 42469,
    "preview": "{\n  \"version\": \"1.0.0\",\n  \"generated\": \"2026-03-18T21:32:49.263Z\",\n  \"stack\": {\n    \"primaryLanguage\": \"typescript\",\n   "
  },
  {
    "path": ".context/docs/development-workflow.md",
    "chars": 4660,
    "preview": "---\ntype: doc\nname: development-workflow\ndescription: Day-to-day engineering processes, branching, and contribution guid"
  },
  {
    "path": ".context/docs/harness-roadmap.md",
    "chars": 8265,
    "preview": "---\ntype: doc\nname: harness-roadmap\ndescription: Product roadmap for evolving dotcontext into a harness engineering plat"
  },
  {
    "path": ".context/docs/harness-split-foundation.md",
    "chars": 18404,
    "preview": "---\ntype: doc\nname: harness-split-foundation\ndescription: Detailed explanation of the first internal split between the C"
  },
  {
    "path": ".context/docs/project-overview.md",
    "chars": 6004,
    "preview": "---\ntype: doc\nname: project-overview\ndescription: High-level overview of the project, its purpose, and key components\nca"
  },
  {
    "path": ".context/docs/qa/README.md",
    "chars": 435,
    "preview": "# Q&A Index\n\nProject type: **cli-tool**\n\nGenerated: 2026-03-18T21:32:55.004Z\n\n## Getting-started\n\n- [How do I set up and"
  },
  {
    "path": ".context/docs/qa/error-handling.md",
    "chars": 3414,
    "preview": "---\nslug: error-handling\ncategory: operations\nstatus: filled\ngeneratedAt: 2026-03-18T21:32:54.231Z\nrelevantFiles:\n  - sr"
  },
  {
    "path": ".context/docs/qa/getting-started.md",
    "chars": 2335,
    "preview": "---\nslug: getting-started\ncategory: getting-started\nstatus: filled\ngeneratedAt: 2026-03-18T21:32:50.399Z\n---\n\n# How do I"
  },
  {
    "path": ".context/docs/qa/project-structure.md",
    "chars": 4016,
    "preview": "---\nslug: project-structure\ncategory: architecture\nstatus: filled\ngeneratedAt: 2026-03-18T21:32:54.231Z\nrelevantFiles:\n "
  },
  {
    "path": ".context/docs/testing-strategy.md",
    "chars": 5068,
    "preview": "---\ntype: doc\nname: testing-strategy\ndescription: Test frameworks, patterns, coverage requirements, and quality gates\nca"
  },
  {
    "path": ".context/docs/tooling.md",
    "chars": 6913,
    "preview": "---\ntype: doc\nname: tooling\ndescription: Scripts, IDE settings, automation, and developer productivity tips\ncategory: to"
  },
  {
    "path": ".context/skills/README.md",
    "chars": 3408,
    "preview": "# Skills\n\nOn-demand expertise for AI agents. Skills are task-specific procedures that get activated when relevant.\n\n> Pr"
  },
  {
    "path": ".context/skills/api-design/SKILL.md",
    "chars": 6156,
    "preview": "---\ntype: skill\nname: MCP Tool Design\ndescription: Design MCP tools and gateway interfaces for the dotcontext server\nski"
  },
  {
    "path": ".context/skills/bug-investigation/SKILL.md",
    "chars": 6170,
    "preview": "---\ntype: skill\nname: Bug Investigation\ndescription: Systematic bug investigation and root cause analysis\nskillSlug: bug"
  },
  {
    "path": ".context/skills/code-review/SKILL.md",
    "chars": 5706,
    "preview": "---\ntype: skill\nname: Code Review\ndescription: Review code quality, patterns, and best practices\nskillSlug: code-review\n"
  },
  {
    "path": ".context/skills/commit-message/SKILL.md",
    "chars": 5455,
    "preview": "---\ntype: skill\nname: Commit Message\ndescription: Generate commit messages following conventional commits with scope det"
  },
  {
    "path": ".context/skills/documentation/SKILL.md",
    "chars": 5371,
    "preview": "---\ntype: skill\nname: Documentation\ndescription: Generate and update technical documentation\nskillSlug: documentation\nph"
  },
  {
    "path": ".context/skills/feature-breakdown/SKILL.md",
    "chars": 6073,
    "preview": "---\ntype: skill\nname: Feature Breakdown\ndescription: Break down features into implementable tasks\nskillSlug: feature-bre"
  },
  {
    "path": ".context/skills/pr-review/SKILL.md",
    "chars": 5116,
    "preview": "---\ntype: skill\nname: PR Review\ndescription: Review pull requests against team standards and best practices\nskillSlug: p"
  },
  {
    "path": ".context/skills/refactoring/SKILL.md",
    "chars": 6082,
    "preview": "---\ntype: skill\nname: Refactoring\ndescription: Safe code refactoring with step-by-step approach\nskillSlug: refactoring\np"
  },
  {
    "path": ".context/skills/security-audit/SKILL.md",
    "chars": 5716,
    "preview": "---\ntype: skill\nname: Security Audit\ndescription: Security review checklist for code and infrastructure\nskillSlug: secur"
  },
  {
    "path": ".context/skills/test-generation/SKILL.md",
    "chars": 7087,
    "preview": "---\ntype: skill\nname: Test Generation\ndescription: Generate comprehensive test cases for code\nskillSlug: test-generation"
  },
  {
    "path": ".env.example",
    "chars": 265,
    "preview": "# OpenRouter API Configuration\nOPENROUTER_API_KEY=your_openrouter_api_key_here\n\n# Optional: Override default model\n# OPE"
  },
  {
    "path": ".github/PULL_REQUEST_BODY.md",
    "chars": 525,
    "preview": "## Summary\n\n<!-- Brief description of what this PR does and why -->\n\n## Changes\n\n<!-- List the key changes -->\n\n-\n\n## Br"
  },
  {
    "path": ".github/workflows/ci.yml",
    "chars": 1937,
    "preview": "name: CI\n\non:\n  push:\n    branches: [ main, develop ]\n  pull_request:\n    branches: [ main ]\n\njobs:\n  test:\n    runs-on:"
  },
  {
    "path": ".github/workflows/release.yml",
    "chars": 1564,
    "preview": "name: Release\n\non:\n  push:\n    tags:\n      - 'v*'\n  workflow_dispatch:\n\njobs:\n  verify-mcp-package:\n    runs-on: ubuntu-"
  },
  {
    "path": ".gitignore",
    "chars": 691,
    "preview": "# Dependencies\nnode_modules/\n\n# Build output\ndist/\n*.tsbuildinfo\n\n# Environment files\n.env\n.env.*\n!.env.example\n\n# Logs\n"
  },
  {
    "path": ".npmignore",
    "chars": 399,
    "preview": "# Source files\nsrc/\n*.ts\n\n# Configuration files\ntsconfig.json\n.env\n.env.*\n!.env.example\n\n# Development files\nnode_module"
  },
  {
    "path": "AGENTS.md",
    "chars": 1372,
    "preview": "# Dotcontext Agent Instructions\n\nThis repository exposes one runtime through three surfaces:\n\n```text\ncli -> harness <- "
  },
  {
    "path": "ARCHITECTURE.md",
    "chars": 6071,
    "preview": "# Dotcontext Harness Architecture\n\nThis document explains how dotcontext works as a harness engineering runtime, how the"
  },
  {
    "path": "CHANGELOG.md",
    "chars": 71222,
    "preview": "# Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Change"
  },
  {
    "path": "CLAUDE.md",
    "chars": 1550,
    "preview": "# Dotcontext Repository Guide\n\nThis repository is the source for the dotcontext runtime and its operator/adaptor surface"
  },
  {
    "path": "CONTRIBUTING.md",
    "chars": 3936,
    "preview": "# Contributing to dotcontext\n\nDotcontext is now organized around an explicit runtime split:\n\n```text\ncli -> harness <- m"
  },
  {
    "path": "CONVENTIONS.md",
    "chars": 2005,
    "preview": "# Project Rules and Guidelines\n\n> Auto-generated from .context/docs on 2026-03-18T21:47:40.751Z\n\n## README\n\n# Documentat"
  },
  {
    "path": "LICENSE",
    "chars": 1073,
    "preview": "MIT License\n\nCopyright (c) 2024 AI Coders Academy\n\nPermission is hereby granted, free of charge, to any person obtaining"
  },
  {
    "path": "README.md",
    "chars": 24738,
    "preview": "# @dotcontext/cli\n\n[![npm version](https://badge.fury.io/js/@dotcontext%2Fcli.svg)](https://www.npmjs.com/package/@dotco"
  },
  {
    "path": "docs/CONTEXT-WORKFLOW-HARNESS-CLI-PTBR.md",
    "chars": 14801,
    "preview": "# Guia Educativo: Contexto, Workflow, Harness e CLI no Dotcontext\n\nEste material explica como o dotcontext organiza cont"
  },
  {
    "path": "docs/GUIDE.md",
    "chars": 10036,
    "preview": "# Dotcontext Guide\n\n`dotcontext` ships separate CLI and MCP package surfaces for shared AI context, PREVC workflow track"
  },
  {
    "path": "example-documentation.ts",
    "chars": 1176,
    "preview": "/**\n * Example script demonstrating how to scaffold documentation and agent playbooks\n * programmatically without going "
  },
  {
    "path": "jest.config.js",
    "chars": 542,
    "preview": "/** @type {import('jest').Config} */\nmodule.exports = {\n  preset: 'ts-jest',\n  testEnvironment: 'node',\n  roots: ['<root"
  },
  {
    "path": "package.json",
    "chars": 2742,
    "preview": "{\n  \"name\": \"@dotcontext/cli\",\n  \"version\": \"0.9.2\",\n  \"description\": \"Harness engineering runtime for AI-assisted softw"
  },
  {
    "path": "prompts/update_plan_prompt.md",
    "chars": 2555,
    "preview": "# Prompt: Update Collaboration Plans\n\n## Purpose\nYou are an AI assistant responsible for refining collaboration plans th"
  },
  {
    "path": "prompts/update_scaffold_prompt.md",
    "chars": 1235,
    "preview": "# Prompt: Update Repository Documentation and Agent Playbooks\n\n## Purpose\nYou are an AI assistant responsible for refres"
  },
  {
    "path": "scripts/build-package-bundles.js",
    "chars": 5647,
    "preview": "#!/usr/bin/env node\n\nconst fs = require('fs');\nconst path = require('path');\n\nconst repoRoot = path.resolve(__dirname, '"
  },
  {
    "path": "scripts/release-packages.js",
    "chars": 3071,
    "preview": "#!/usr/bin/env node\n\nconst fs = require('fs');\nconst path = require('path');\nconst semver = require('semver');\nconst { e"
  },
  {
    "path": "scripts/smoke-package-bundles.js",
    "chars": 4152,
    "preview": "#!/usr/bin/env node\n\nconst fs = require('fs');\nconst path = require('path');\nconst { execFileSync } = require('child_pro"
  },
  {
    "path": "scripts/test-mcp.js",
    "chars": 2000,
    "preview": "#!/usr/bin/env node\n/**\n * Simple MCP test client for local development\n *\n * Usage: node scripts/test-mcp.js\n */\n\nconst"
  },
  {
    "path": "src/cli/index.test.ts",
    "chars": 712,
    "preview": "import {\n  MCPInstallService,\n  SyncService,\n  ImportRulesService,\n  ImportAgentsService,\n  ExportRulesService,\n  Report"
  },
  {
    "path": "src/cli/index.ts",
    "chars": 1073,
    "preview": "/**\n * CLI boundary exports.\n *\n * This module defines the operator-facing surface that is expected to\n * become the fut"
  },
  {
    "path": "src/cli.test.ts",
    "chars": 2645,
    "preview": "import { execSync } from 'child_process';\nimport * as path from 'path';\n\ndescribe('CLI Commands', () => {\n  const cliPat"
  },
  {
    "path": "src/generators/agents/agentConfig.ts",
    "chars": 6687,
    "preview": "import { AgentType } from './agentTypes';\n\nexport const AGENT_RESPONSIBILITIES: Record<AgentType, string[]> = {\n  'code-"
  },
  {
    "path": "src/generators/agents/agentGenerator.test.ts",
    "chars": 3509,
    "preview": "import * as os from 'os';\nimport * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { AgentGenerator } from "
  },
  {
    "path": "src/generators/agents/agentGenerator.ts",
    "chars": 12426,
    "preview": "import * as path from 'path';\nimport { RepoStructure } from '../../types';\nimport { GeneratorUtils } from '../shared';\ni"
  },
  {
    "path": "src/generators/agents/agentTypes.ts",
    "chars": 615,
    "preview": "export const AGENT_TYPES = [\n  'code-reviewer',\n  'bug-fixer',\n  'feature-developer',\n  'refactoring-specialist',\n  'tes"
  },
  {
    "path": "src/generators/agents/index.ts",
    "chars": 201,
    "preview": "export { AgentGenerator } from './agentGenerator';\nexport { AGENT_TYPES, AgentType, IMPORTANT_FILES } from './agentTypes"
  },
  {
    "path": "src/generators/agents/templates/index.ts",
    "chars": 120,
    "preview": "export { renderAgentIndex } from './indexTemplate';\nexport type { AgentTemplateContext, DocTouchpoint } from './types';\n"
  },
  {
    "path": "src/generators/agents/templates/indexTemplate.ts",
    "chars": 1224,
    "preview": "import { AgentType } from '../agentTypes';\nimport { AGENT_RESPONSIBILITIES } from '../agentConfig';\n\nexport function ren"
  },
  {
    "path": "src/generators/agents/templates/types.ts",
    "chars": 534,
    "preview": "import { AgentType } from '../agentTypes';\nimport { SemanticContext } from '../../../services/semantic';\n\nexport interfa"
  },
  {
    "path": "src/generators/documentation/codebaseMapGenerator.ts",
    "chars": 23908,
    "preview": "/**\n * Codebase Map Generator\n *\n * Generates a summary JSON file for the codebase structure, stack,\n * architecture, de"
  },
  {
    "path": "src/generators/documentation/documentationGenerator.test.ts",
    "chars": 4596,
    "preview": "import * as os from 'os';\nimport * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { DocumentationGenerator"
  },
  {
    "path": "src/generators/documentation/documentationGenerator.ts",
    "chars": 11257,
    "preview": "import * as path from 'path';\nimport * as fs from 'fs-extra';\nimport { RepoStructure } from '../../types';\nimport { Gene"
  },
  {
    "path": "src/generators/documentation/guideRegistry.ts",
    "chars": 2112,
    "preview": "import { GuideMeta } from './templates/types';\n\nexport const DOCUMENT_GUIDES: GuideMeta[] = [\n  {\n    key: 'project-over"
  },
  {
    "path": "src/generators/documentation/index.ts",
    "chars": 261,
    "preview": "export { DocumentationGenerator } from './documentationGenerator';\nexport { CodebaseMapGenerator } from './codebaseMapGe"
  },
  {
    "path": "src/generators/documentation/templates/common.ts",
    "chars": 5654,
    "preview": "import * as path from 'path';\nimport { DirectoryStat, DocumentationTemplateContext } from './types';\nimport type { Extra"
  },
  {
    "path": "src/generators/documentation/templates/index.ts",
    "chars": 134,
    "preview": "export { renderIndex } from './indexTemplate';\nexport type { DocumentationTemplateContext, GuideMeta, DirectoryStat } fr"
  },
  {
    "path": "src/generators/documentation/templates/indexTemplate.ts",
    "chars": 821,
    "preview": "import { buildDocumentMapTable, formatDirectoryList } from './common';\nimport { DocumentationTemplateContext } from './t"
  },
  {
    "path": "src/generators/documentation/templates/types.ts",
    "chars": 558,
    "preview": "import { RepoStructure } from '../../../types';\nimport { SemanticContext } from '../../../services/semantic';\n\nexport in"
  },
  {
    "path": "src/generators/plans/index.ts",
    "chars": 49,
    "preview": "export { PlanGenerator } from './planGenerator';\n"
  },
  {
    "path": "src/generators/plans/planGenerator.test.ts",
    "chars": 2431,
    "preview": "import * as os from 'os';\nimport * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { PlanGenerator } from '"
  },
  {
    "path": "src/generators/plans/planGenerator.ts",
    "chars": 5252,
    "preview": "import * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { GeneratorUtils } from '../shared';\nimport { Agen"
  },
  {
    "path": "src/generators/plans/templates/indexTemplate.ts",
    "chars": 908,
    "preview": "import { PlanIndexEntry } from './types';\n\nexport function renderPlanIndex(entries: PlanIndexEntry[]): string {\n  const "
  },
  {
    "path": "src/generators/plans/templates/planTemplate.ts",
    "chars": 11181,
    "preview": "/**\n * REFERENCE ONLY - This file is not used by generators anymore.\n *\n * Scaffold structures are now defined in:\n * sr"
  },
  {
    "path": "src/generators/plans/templates/types.ts",
    "chars": 719,
    "preview": "import { AgentType } from '../../agents/agentTypes';\nimport { GuideMeta } from '../../documentation/templates/types';\nim"
  },
  {
    "path": "src/generators/shared/contextGenerator.ts",
    "chars": 270,
    "preview": "import { FileMapper } from '../../utils/fileMapper';\n\nexport class ContextGenerator {\n  constructor(protected readonly f"
  },
  {
    "path": "src/generators/shared/directoryTemplateHelpers.ts",
    "chars": 290,
    "preview": "export function formatDirectoryList(directories: string[], placeholderMessage?: string): string {\n  if (!directories.len"
  },
  {
    "path": "src/generators/shared/generatorUtils.ts",
    "chars": 2948,
    "preview": "import * as fs from 'fs-extra';\nimport * as path from 'path';\nimport { RepoStructure } from '../../types';\nimport { colo"
  },
  {
    "path": "src/generators/shared/index.ts",
    "chars": 275,
    "preview": "export { GeneratorUtils } from './generatorUtils';\nexport { ContextGenerator } from './contextGenerator';\nexport { forma"
  },
  {
    "path": "src/generators/shared/scaffoldStructures.ts",
    "chars": 469,
    "preview": "/**\n * Scaffold Structure Definitions (DEPRECATED)\n *\n * This file is maintained for backward compatibility.\n * All func"
  },
  {
    "path": "src/generators/shared/structures/agents/definitions.ts",
    "chars": 26594,
    "preview": "/**\n * Agent structure definitions with static default content\n */\n\nimport { createAgentStructure, AgentDefaultContent }"
  },
  {
    "path": "src/generators/shared/structures/agents/factory.ts",
    "chars": 4654,
    "preview": "/**\n * Factory function for creating agent structures\n */\n\nimport { ScaffoldStructure, ScaffoldSection } from '../types'"
  },
  {
    "path": "src/generators/shared/structures/agents/index.ts",
    "chars": 526,
    "preview": "/**\n * Agent structure exports\n */\n\nexport { createAgentStructure } from './factory';\nexport {\n  codeReviewerStructure,\n"
  },
  {
    "path": "src/generators/shared/structures/documentation/apiReference.ts",
    "chars": 3911,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const apiReferenceStructure: ScaffoldStructure = {\n  fileType: 'do"
  },
  {
    "path": "src/generators/shared/structures/documentation/architecture.ts",
    "chars": 6881,
    "preview": "import { ScaffoldStructure } from '../types';\n\nconst SEMANTIC_SNAPSHOT_GUIDANCE =\n  'Use `context({ action: \"getMap\", se"
  },
  {
    "path": "src/generators/shared/structures/documentation/dataFlow.ts",
    "chars": 3496,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const dataFlowStructure: ScaffoldStructure = {\n  fileType: 'doc',\n"
  },
  {
    "path": "src/generators/shared/structures/documentation/glossary.ts",
    "chars": 2933,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const glossaryStructure: ScaffoldStructure = {\n  fileType: 'doc',\n"
  },
  {
    "path": "src/generators/shared/structures/documentation/index.ts",
    "chars": 689,
    "preview": "/**\n * Documentation structure definitions\n */\n\nexport { projectOverviewStructure } from './projectOverview';\nexport { a"
  },
  {
    "path": "src/generators/shared/structures/documentation/migration.ts",
    "chars": 4056,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const migrationStructure: ScaffoldStructure = {\n  fileType: 'doc',"
  },
  {
    "path": "src/generators/shared/structures/documentation/onboarding.ts",
    "chars": 4210,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const onboardingStructure: ScaffoldStructure = {\n  fileType: 'doc'"
  },
  {
    "path": "src/generators/shared/structures/documentation/projectOverview.ts",
    "chars": 6829,
    "preview": "import { ScaffoldStructure } from '../types';\n\nconst SEMANTIC_SNAPSHOT_GUIDANCE =\n  'Use `context({ action: \"getMap\", se"
  },
  {
    "path": "src/generators/shared/structures/documentation/security.ts",
    "chars": 3380,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const securityStructure: ScaffoldStructure = {\n  fileType: 'doc',\n"
  },
  {
    "path": "src/generators/shared/structures/documentation/testing.ts",
    "chars": 4207,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const testingStrategyStructure: ScaffoldStructure = {\n  fileType: "
  },
  {
    "path": "src/generators/shared/structures/documentation/tooling.ts",
    "chars": 3549,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const toolingStructure: ScaffoldStructure = {\n  fileType: 'doc',\n "
  },
  {
    "path": "src/generators/shared/structures/documentation/troubleshooting.ts",
    "chars": 3875,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const troubleshootingStructure: ScaffoldStructure = {\n  fileType: "
  },
  {
    "path": "src/generators/shared/structures/documentation/workflow.ts",
    "chars": 3929,
    "preview": "import { ScaffoldStructure } from '../types';\n\nexport const developmentWorkflowStructure: ScaffoldStructure = {\n  fileTy"
  },
  {
    "path": "src/generators/shared/structures/index.ts",
    "chars": 556,
    "preview": "/**\n * Scaffold structures index\n *\n * This file serves as the main barrel export for all scaffold structures,\n * provid"
  },
  {
    "path": "src/generators/shared/structures/plans/index.ts",
    "chars": 84,
    "preview": "/**\n * Plan structure exports\n */\n\nexport { planStructure } from './planStructure';\n"
  },
  {
    "path": "src/generators/shared/structures/plans/planStructure.ts",
    "chars": 1717,
    "preview": "/**\n * Plan structure definition\n */\n\nimport { ScaffoldStructure } from '../types';\n\nexport const planStructure: Scaffol"
  },
  {
    "path": "src/generators/shared/structures/registry.ts",
    "chars": 3196,
    "preview": "/**\n * Scaffold structures registry and lookup functions\n */\n\nimport { ScaffoldFileType } from '../../../types/scaffoldF"
  },
  {
    "path": "src/generators/shared/structures/serialization.ts",
    "chars": 4522,
    "preview": "/**\n * Serialization functions for scaffold structures\n */\n\nimport { ScaffoldStructure, ScaffoldSection } from './types'"
  },
  {
    "path": "src/generators/shared/structures/skills/definitions.ts",
    "chars": 16262,
    "preview": "/**\n * Skill structure definitions with static default content\n */\n\nimport { createSkillStructure, SkillDefaultContent }"
  },
  {
    "path": "src/generators/shared/structures/skills/factory.ts",
    "chars": 3064,
    "preview": "/**\n * Factory function for creating skill structures\n */\n\nimport { ScaffoldStructure, ScaffoldSection } from '../types'"
  },
  {
    "path": "src/generators/shared/structures/skills/index.ts",
    "chars": 655,
    "preview": "/**\n * Skill structure exports\n */\n\nexport { createSkillStructure } from './factory';\nexport {\n  commitMessageSkillStruc"
  },
  {
    "path": "src/generators/shared/structures/types.ts",
    "chars": 2349,
    "preview": "/**\n * Type definitions for scaffold structures\n */\n\nimport { ScaffoldFileType } from '../../../types/scaffoldFrontmatte"
  },
  {
    "path": "src/generators/shared/structures/validation.ts",
    "chars": 1381,
    "preview": "/**\n * Validation functions for scaffold structures\n */\n\nimport { ScaffoldStructure } from './types';\nimport { SCAFFOLD_"
  },
  {
    "path": "src/generators/skills/index.ts",
    "chars": 314,
    "preview": "/**\n * Skills Generator Module\n */\n\nexport {\n  SkillGenerator,\n  SkillGeneratorOptions,\n  SkillGeneratorResult,\n  create"
  },
  {
    "path": "src/generators/skills/skillGenerator.test.ts",
    "chars": 2046,
    "preview": "import * as os from 'os';\nimport * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { SkillGenerator } from "
  },
  {
    "path": "src/generators/skills/skillGenerator.ts",
    "chars": 7361,
    "preview": "/**\n * Skill Generator\n *\n * Scaffolds skill directories and SKILL.md files.\n * Generates scaffold v2 files with fillabl"
  },
  {
    "path": "src/generators/skills/templates/indexTemplate.ts",
    "chars": 3299,
    "preview": "/**\n * Skills Index (README.md) Template\n */\n\nimport { Skill } from '../../../workflow/skills';\n\nexport interface Skills"
  },
  {
    "path": "src/generators/skills/templates/skillTemplate.ts",
    "chars": 2510,
    "preview": "/**\n * SKILL.md Template\n *\n * REFERENCE ONLY - This file is not used by generators anymore.\n *\n * Scaffold structures a"
  },
  {
    "path": "src/harness/index.test.ts",
    "chars": 1216,
    "preview": "import {\n  WorkflowService,\n  HarnessAgentsService,\n  HarnessPlansService,\n  HarnessContextService,\n  HarnessSkillsServi"
  },
  {
    "path": "src/harness/index.ts",
    "chars": 2988,
    "preview": "/**\n * Harness boundary exports.\n *\n * This module defines the reusable runtime surface that is expected to\n * become th"
  },
  {
    "path": "src/index.ts",
    "chars": 43940,
    "preview": "#!/usr/bin/env node\n\nimport { Command } from 'commander';\nimport * as path from 'path';\nimport inquirer from 'inquirer';"
  },
  {
    "path": "src/mcp/bin.test.ts",
    "chars": 3644,
    "preview": "const mockRun = jest.fn();\nconst mockResolveMcpInstallToolSelection = jest.fn();\nconst mockStartMCPServer = jest.fn();\n\n"
  },
  {
    "path": "src/mcp/bin.ts",
    "chars": 6084,
    "preview": "#!/usr/bin/env node\n\n/**\n * Dedicated MCP package binary for `@dotcontext/mcp`.\n *\n * Default behavior starts the MCP se"
  },
  {
    "path": "src/mcp/index.test.ts",
    "chars": 886,
    "preview": "import {\n  AIContextMCPServer,\n  startMCPServer,\n  handleExplore,\n  handleContext,\n  handlePlan,\n  handleAgent,\n  handle"
  },
  {
    "path": "src/mcp/index.ts",
    "chars": 1014,
    "preview": "/**\n * MCP boundary exports.\n *\n * This module defines the protocol adapter surface that is expected to\n * become the fu"
  },
  {
    "path": "src/prompts/defaults.ts",
    "chars": 4094,
    "preview": "export const UPDATE_SCAFFOLD_PROMPT_FALLBACK = `# Prompt: Update Repository Documentation and Agent Playbooks\n\n## Purpos"
  },
  {
    "path": "src/services/autoFill/autoFillService.ts",
    "chars": 19059,
    "preview": "/**\n * AutoFillService - Generates documentation content from semantic analysis\n *\n * This service fills scaffold templa"
  },
  {
    "path": "src/services/autoFill/index.ts",
    "chars": 70,
    "preview": "export { AutoFillService, AutoFillContext } from './autoFillService';\n"
  },
  {
    "path": "src/services/cli/index.ts",
    "chars": 606,
    "preview": "/**\n * CLI service exports.\n *\n * These services belong to the operator-facing CLI boundary.\n */\n\nexport {\n  MCPInstallS"
  },
  {
    "path": "src/services/cli/mcpInstallService.test.ts",
    "chars": 21780,
    "preview": "import * as os from 'os';\nimport * as path from 'path';\nimport * as fs from 'fs-extra';\nimport {\n  MCPInstallService,\n  "
  },
  {
    "path": "src/services/cli/mcpInstallService.ts",
    "chars": 22611,
    "preview": "/**\n * MCP Install Service\n *\n * CLI-facing installation service for configuring the dotcontext MCP server\n * in various"
  },
  {
    "path": "src/services/cli/stateDetector.ts",
    "chars": 5400,
    "preview": "/**\n * StateDetector - Detects the current state of the project's context documentation.\n *\n * States:\n * - new: No .con"
  },
  {
    "path": "src/services/export/contextExportService.ts",
    "chars": 5877,
    "preview": "/**\n * Context Export Service\n *\n * Unified export of docs, agents, and skills to AI tool directories.\n * Orchestrates E"
  },
  {
    "path": "src/services/export/exportRulesService.ts",
    "chars": 10627,
    "preview": "/**\n * Export Rules Service\n *\n * Bidirectional sync: export rules from .context to AI tool directories.\n */\n\nimport * a"
  },
  {
    "path": "src/services/export/index.ts",
    "chars": 597,
    "preview": "export { ExportRulesService, EXPORT_PRESETS } from './exportRulesService';\nexport type { ExportOptions, ExportResult, Ex"
  },
  {
    "path": "src/services/export/skillExportService.test.ts",
    "chars": 1972,
    "preview": "import * as os from 'os';\nimport * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { SkillExportService } f"
  },
  {
    "path": "src/services/export/skillExportService.ts",
    "chars": 8813,
    "preview": "/**\n * Skill Export Service\n *\n * Export skills from .context/skills to AI tool skill directories.\n */\n\nimport * as path"
  },
  {
    "path": "src/services/harness/agentsService.ts",
    "chars": 4602,
    "preview": "/**\n * Harness Agents Service\n *\n * Transport-agnostic agent discovery and orchestration logic.\n */\n\nimport {\n  PHASE_NA"
  },
  {
    "path": "src/services/harness/contextService.ts",
    "chars": 18824,
    "preview": "/**\n * Harness Context Service\n *\n * Transport-agnostic context, semantic analysis, and scaffold orchestration logic.\n *"
  },
  {
    "path": "src/services/harness/contextTools.test.ts",
    "chars": 6752,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport {\n  fillSingleFileTool,\n"
  },
  {
    "path": "src/services/harness/contextTools.ts",
    "chars": 39182,
    "preview": "import * as fs from 'fs-extra';\nimport { glob } from 'glob';\nimport * as path from 'path';\nimport { TreeSitterLayer } fr"
  },
  {
    "path": "src/services/harness/datasetService.test.ts",
    "chars": 2143,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { HarnessExecutionServic"
  },
  {
    "path": "src/services/harness/datasetService.ts",
    "chars": 10547,
    "preview": "import * as fs from 'fs-extra';\nimport * as path from 'path';\nimport { randomUUID } from 'crypto';\n\nimport { HarnessRunt"
  },
  {
    "path": "src/services/harness/executionService.test.ts",
    "chars": 1484,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { HarnessExecutionServic"
  },
  {
    "path": "src/services/harness/executionService.ts",
    "chars": 9249,
    "preview": "import {\n  HarnessRuntimeStateService,\n  type AddArtifactInput,\n  type AppendTraceInput,\n  type CheckpointInput,\n  type "
  },
  {
    "path": "src/services/harness/index.ts",
    "chars": 3471,
    "preview": "/**\n * Harness service exports.\n *\n * These services hold transport-agnostic harness logic that can be consumed\n * by MC"
  },
  {
    "path": "src/services/harness/plansService.ts",
    "chars": 8502,
    "preview": "/**\n * Harness Plans Service\n *\n * Transport-agnostic plan management and execution tracking logic.\n */\n\nimport * as pat"
  },
  {
    "path": "src/services/harness/policyService.test.ts",
    "chars": 4074,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { HarnessPolicyService }"
  },
  {
    "path": "src/services/harness/policyService.ts",
    "chars": 18400,
    "preview": "import * as fs from 'fs-extra';\nimport * as path from 'path';\nimport { StackDetector, type StackInfo } from '../stack';\n"
  },
  {
    "path": "src/services/harness/replayService.test.ts",
    "chars": 2254,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { HarnessExecutionServic"
  },
  {
    "path": "src/services/harness/replayService.ts",
    "chars": 9426,
    "preview": "import * as fs from 'fs-extra';\nimport * as path from 'path';\nimport { randomUUID } from 'crypto';\n\nimport type {\n  Harn"
  },
  {
    "path": "src/services/harness/runtimeStateService.test.ts",
    "chars": 3425,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\nimport {\n  HarnessRuntimeStateSe"
  },
  {
    "path": "src/services/harness/runtimeStateService.ts",
    "chars": 12361,
    "preview": "/**\n * Harness Runtime State Service\n *\n * Transport-agnostic persistence for sessions, artifacts, traces, and checkpoin"
  },
  {
    "path": "src/services/harness/sensorCatalogService.ts",
    "chars": 9501,
    "preview": "/**\n * Harness Sensor Catalog Service\n *\n * Bootstraps a user-editable sensor catalog under .context/harness/sensors.jso"
  },
  {
    "path": "src/services/harness/sensorsService.test.ts",
    "chars": 1562,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { HarnessRuntimeStateServ"
  },
  {
    "path": "src/services/harness/sensorsService.ts",
    "chars": 4629,
    "preview": "/**\n * Harness Sensors Service\n *\n * Registers and executes quality sensors, then persists the run as a trace\n * entry i"
  },
  {
    "path": "src/services/harness/skillsService.ts",
    "chars": 11437,
    "preview": "/**\n * Harness Skills Service\n *\n * Transport-agnostic skill discovery, export, and fill orchestration logic.\n */\n\nimpor"
  },
  {
    "path": "src/services/harness/taskContractsService.test.ts",
    "chars": 2643,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\nimport { HarnessRuntimeStateServ"
  },
  {
    "path": "src/services/harness/taskContractsService.ts",
    "chars": 8885,
    "preview": "/**\n * Harness Task Contracts Service\n *\n * Persists structured task and handoff contracts and evaluates whether a task\n"
  },
  {
    "path": "src/services/harness/workflowStateService.ts",
    "chars": 6918,
    "preview": "/**\n * Harness Workflow State Service\n *\n * Canonical persistence for workflow orchestration state. PREVC status now\n * "
  },
  {
    "path": "src/services/import/agentsDetector.ts",
    "chars": 5155,
    "preview": "import * as path from 'path';\nimport * as fs from 'fs-extra';\nimport { glob } from 'glob';\nimport type { RuleFileInfo, D"
  },
  {
    "path": "src/services/import/importAgentsService.ts",
    "chars": 6960,
    "preview": "import * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { colors, symbols, typography } from '../../utils/"
  },
  {
    "path": "src/services/import/importRulesService.ts",
    "chars": 8131,
    "preview": "import * as path from 'path';\nimport * as fs from 'fs-extra';\n\nimport { colors, symbols, typography } from '../../utils/"
  },
  {
    "path": "src/services/import/index.ts",
    "chars": 272,
    "preview": "export * from './types';\nexport * from './presets';\nexport { RulesDetector } from './rulesDetector';\nexport { AgentsDete"
  },
  {
    "path": "src/services/import/presets.ts",
    "chars": 1816,
    "preview": "/**\n * Import Presets\n *\n * Rule and agent source definitions for import/detection services.\n * Derived from the unified"
  },
  {
    "path": "src/services/import/rulesDetector.ts",
    "chars": 9459,
    "preview": "import * as path from 'path';\nimport * as fs from 'fs-extra';\nimport { glob } from 'glob';\nimport type { RuleFileInfo, D"
  },
  {
    "path": "src/services/import/types.ts",
    "chars": 1762,
    "preview": "import type { CLIInterface } from '../../utils/cliUI';\nimport type { TranslateFn } from '../../utils/i18n';\n\nexport type"
  },
  {
    "path": "src/services/mcp/README.md",
    "chars": 4727,
    "preview": "# MCP Tools Reference\n\nThis directory documents the MCP adapter surface over the harness runtime.\n\nCLI-only concerns suc"
  },
  {
    "path": "src/services/mcp/actionLogger.test.ts",
    "chars": 3017,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { HarnessRuntimeStateSer"
  },
  {
    "path": "src/services/mcp/actionLogger.ts",
    "chars": 4892,
    "preview": "/**\n * MCP Action Logger\n *\n * Records MCP tool activity into harness session traces instead of maintaining\n * a separat"
  },
  {
    "path": "src/services/mcp/gateway/agent.ts",
    "chars": 1985,
    "preview": "/**\n * Agent Gateway Handler\n *\n * Handles agent orchestration and discovery operations.\n * Replaces: discoverAgents, ge"
  },
  {
    "path": "src/services/mcp/gateway/context.test.ts",
    "chars": 2502,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { SemanticContextBuilder"
  },
  {
    "path": "src/services/mcp/gateway/context.ts",
    "chars": 4600,
    "preview": "/**\n * Context Gateway Handler\n *\n * Handles context scaffolding and semantic context operations.\n * Replaces: checkScaf"
  },
  {
    "path": "src/services/mcp/gateway/explore.ts",
    "chars": 2474,
    "preview": "/**\n * Explore Gateway Handler\n *\n * Handles file and code exploration operations.\n * Replaces: readFile, listFiles, ana"
  },
  {
    "path": "src/services/mcp/gateway/harness.test.ts",
    "chars": 5602,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { handleHarness } from '"
  },
  {
    "path": "src/services/mcp/gateway/harness.ts",
    "chars": 12183,
    "preview": "import {\n  HarnessExecutionService,\n  HarnessReplayService,\n  HarnessDatasetService,\n  type HarnessPolicyEffect,\n  type "
  },
  {
    "path": "src/services/mcp/gateway/index.ts",
    "chars": 2030,
    "preview": "/**\n * Gateway Tools Module\n *\n * Exports all gateway handlers, types, and response utilities.\n * This module consolidat"
  },
  {
    "path": "src/services/mcp/gateway/metrics.test.ts",
    "chars": 1089,
    "preview": "import {\n  getMetricsSummary,\n  recordFileRead,\n  resetMetrics,\n} from './metrics';\n\ndescribe('metrics recommendations',"
  },
  {
    "path": "src/services/mcp/gateway/metrics.ts",
    "chars": 5004,
    "preview": "/**\n * Metrics Service\n *\n * Tracks context tool usage vs file reads to measure improvement.\n * Helps evaluate the effec"
  },
  {
    "path": "src/services/mcp/gateway/plan.ts",
    "chars": 3051,
    "preview": "/**\n * Plan Gateway Handler\n *\n * Handles plan management and execution tracking operations.\n * Replaces: linkPlan, getL"
  },
  {
    "path": "src/services/mcp/gateway/response.ts",
    "chars": 4028,
    "preview": "/**\n * MCP Response Helpers\n *\n * Standardized response creation for MCP tool handlers.\n */\n\n/**\n * MCP Tool Response ty"
  },
  {
    "path": "src/services/mcp/gateway/shared.ts",
    "chars": 213,
    "preview": "/**\n * Shared Utilities for Gateway Handlers\n *\n * Common utilities used across multiple gateway handlers.\n */\n\nexport {"
  },
  {
    "path": "src/services/mcp/gateway/skill.ts",
    "chars": 1847,
    "preview": "/**\n * Skill Gateway Handler\n *\n * Handles skill management operations.\n * Replaces: listSkills, getSkillContent, getSki"
  },
  {
    "path": "src/services/mcp/gateway/sync.ts",
    "chars": 7644,
    "preview": "/**\n * Sync Gateway Handler\n *\n * Handles import/export synchronization operations.\n * Replaces: exportRules, exportDocs"
  },
  {
    "path": "src/services/mcp/gateway/types.ts",
    "chars": 6888,
    "preview": "/**\n * Gateway Tool Types\n *\n * Type definitions for MCP gateway tool parameters and responses.\n *\n * Note: Some gateway"
  },
  {
    "path": "src/services/mcp/gateway/workflowAdvance.ts",
    "chars": 5561,
    "preview": "/**\n * Workflow Advance Handler\n *\n * Handles advancing PREVC workflow to the next phase.\n */\n\nimport * as path from 'pa"
  },
  {
    "path": "src/services/mcp/gateway/workflowInit.ts",
    "chars": 8212,
    "preview": "/**\n * Workflow Init Handler\n *\n * Handles PREVC workflow initialization.\n * Primary entry point for AI to start workflo"
  },
  {
    "path": "src/services/mcp/gateway/workflowManage.test.ts",
    "chars": 9778,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { handlePlan } from './p"
  },
  {
    "path": "src/services/mcp/gateway/workflowManage.ts",
    "chars": 14579,
    "preview": "/**\n * Workflow Manage Handler\n *\n * Handles workflow management operations: handoffs, collaboration, documents, gates, "
  },
  {
    "path": "src/services/mcp/gateway/workflowStatus.test.ts",
    "chars": 1714,
    "preview": "import * as fs from 'fs-extra';\nimport * as os from 'os';\nimport * as path from 'path';\n\nimport { handleWorkflowInit } f"
  },
  {
    "path": "src/services/mcp/gateway/workflowStatus.ts",
    "chars": 2390,
    "preview": "/**\n * Workflow Status Handler\n *\n * Handles PREVC workflow status queries.\n */\n\nimport * as path from 'path';\nimport { "
  },
  {
    "path": "src/services/mcp/gatewayTools.ts",
    "chars": 1811,
    "preview": "/**\n * Gateway Tools\n *\n * Re-exports all gateway handlers, types, and response utilities from the\n * modular gateway di"
  },
  {
    "path": "src/services/mcp/index.ts",
    "chars": 1620,
    "preview": "/**\n * MCP transport adapter exports.\n *\n * Keep this surface focused on the protocol adapter that exposes harness\n * ca"
  },
  {
    "path": "src/services/mcp/mcpInstallService.ts",
    "chars": 376,
    "preview": "/**\n * @deprecated Import from ../cli/mcpInstallService instead.\n *\n * This shim preserves the previous path while the c"
  },
  {
    "path": "src/services/mcp/mcpServer.test.ts",
    "chars": 1815,
    "preview": "import * as os from 'os';\nimport * as path from 'path';\nimport * as fs from 'fs-extra';\nimport { AIContextMCPServer } fr"
  },
  {
    "path": "src/services/mcp/mcpServer.ts",
    "chars": 49946,
    "preview": "/**\n * MCP Server - Model Context Protocol server for dotcontext integration.\n *\n * Exposes consolidated gateway tools p"
  },
  {
    "path": "src/services/qa/index.ts",
    "chars": 346,
    "preview": "/**\n * Q&A Service Module\n *\n * Exports Q&A generation and search functionality.\n */\n\nexport { QAService, type QAEntry, "
  },
  {
    "path": "src/services/qa/patternInferer.ts",
    "chars": 596,
    "preview": "/**\n * Pattern Inferer\n *\n * Backward-compatible adapter for persisted codebase summaries.\n * Functional patterns are no"
  },
  {
    "path": "src/services/qa/qaService.ts",
    "chars": 30394,
    "preview": "/**\n * Q&A Service\n *\n * Generates and manages Q&A content for the codebase.\n * Pre-answers common questions to reduce t"
  },
  {
    "path": "src/services/qa/topicDetector.ts",
    "chars": 10268,
    "preview": "/**\n * Topic Detector Service\n *\n * Dynamically detects Q&A topics based on:\n * 1. Stack detection - Language, framework"
  }
]

// ... and 110 more files (download for full content)

About this extraction

This page contains the full source code of the vinilana/ai-coders-context GitHub repository, extracted and formatted as plain text for AI agents and large language models (LLMs). The extraction includes 310 files (1.9 MB), approximately 473.0k tokens, and a symbol index with 1901 extracted functions, classes, methods, constants, and types. Use this with OpenClaw, Claude, ChatGPT, Cursor, Windsurf, or any other AI tool that accepts text input. You can copy the full output to your clipboard or download it as a .txt file.

Extracted by GitExtract — free GitHub repo to text converter for AI. Built by Nikandr Surkov.

Copied to clipboard!