Documentation

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

Instructions

Updating Scaffold Documentation (.context/docs/)

Scaffold docs use v2 frontmatter:

---
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:

## [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:

---
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