Skip to content
This repository was archived by the owner on Dec 17, 2025. It is now read-only.

Commit 43d3ee5

Browse files
killerappkillerapp
committed
doc: add diagrams
1 parent c861532 commit 43d3ee5

File tree

4 files changed

+265
-63
lines changed

4 files changed

+265
-63
lines changed

‎.context/diagrams/context-window-usage.mmd‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
%%{init: { 'theme': 'dark' } }%%
2+
graph TD
3+
subgraph "Context Window Management"
4+
A[Start New Chat] --> B{Check Model Capacity}
5+
6+
B -->|200K Tokens| C1[Basic Context]
7+
B -->|500K Tokens| C2[Extended Context]
8+
B -->|2M+ Tokens| C3[Full Context]
9+
10+
C1 --> D1[Load Essential Info]
11+
C2 --> D2[Load Extended Info]
12+
C3 --> D3[Load Complete Info]
13+
end
14+
15+
subgraph "200K Token Window"
16+
D1 --> E1[index.md]
17+
E1 --> F1[Key Architecture]
18+
E1 --> G1[Critical Patterns]
19+
end
20+
21+
subgraph "500K Token Window"
22+
D2 --> E2[index.md + docs/]
23+
E2 --> F2[Architecture + Diagrams]
24+
E2 --> G2[Patterns + History]
25+
E2 --> H2[Team Conventions]
26+
end
27+
28+
subgraph "2M+ Token Window"
29+
D3 --> E3[Complete .context/]
30+
E3 --> F3[All Documentation]
31+
E3 --> G3[All Diagrams]
32+
E3 --> H3[Full History]
33+
E3 --> I3[External References]
34+
end
35+
36+
style A fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
37+
style B fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff
38+
39+
%% Basic Context
40+
style C1 fill:#4444ff,stroke:#fff,stroke-width:2px,color:#fff
41+
style D1 fill:#4444ff,stroke:#fff,stroke-width:2px,color:#fff
42+
style E1 fill:#4444ff,stroke:#fff,stroke-width:2px,color:#fff
43+
style F1 fill:#4444ff,stroke:#fff,stroke-width:2px,color:#fff
44+
style G1 fill:#4444ff,stroke:#fff,stroke-width:2px,color:#fff
45+
46+
%% Extended Context
47+
style C2 fill:#33cc33,stroke:#fff,stroke-width:2px,color:#fff
48+
style D2 fill:#33cc33,stroke:#fff,stroke-width:2px,color:#fff
49+
style E2 fill:#33cc33,stroke:#fff,stroke-width:2px,color:#fff
50+
style F2 fill:#33cc33,stroke:#fff,stroke-width:2px,color:#fff
51+
style G2 fill:#33cc33,stroke:#fff,stroke-width:2px,color:#fff
52+
style H2 fill:#33cc33,stroke:#fff,stroke-width:2px,color:#fff
53+
54+
%% Full Context
55+
style C3 fill:#ff4444,stroke:#fff,stroke-width:2px,color:#fff
56+
style D3 fill:#ff4444,stroke:#fff,stroke-width:2px,color:#fff
57+
style E3 fill:#ff4444,stroke:#fff,stroke-width:2px,color:#fff
58+
style F3 fill:#ff4444,stroke:#fff,stroke-width:2px,color:#fff
59+
style G3 fill:#ff4444,stroke:#fff,stroke-width:2px,color:#fff
60+
style H3 fill:#ff4444,stroke:#fff,stroke-width:2px,color:#fff
61+
style I3 fill:#ff4444,stroke:#fff,stroke-width:2px,color:#fff
62+
63+
classDef default fill:#2d2d2d,stroke:#fff,stroke-width:2px,color:#fff

‎.context/diagrams/information-flow.mmd‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
%%{init: { 'theme': 'dark' } }%%
2+
sequenceDiagram
3+
participant Dev as Developer
4+
participant DC as .context/
5+
participant MCP as MCP Server
6+
participant AI as AI Assistant
7+
8+
rect rgba(50, 50, 50, 0.5)
9+
Note over Dev,AI: Initial Setup
10+
Dev->>DC: Create context structure
11+
Dev->>DC: Add documentation
12+
Dev->>DC: Create diagrams
13+
end
14+
15+
rect rgba(50, 50, 50, 0.5)
16+
Note over Dev,AI: Development Flow
17+
Dev->>AI: Start new task
18+
AI->>MCP: Request context
19+
MCP->>DC: Read context
20+
DC-->>MCP: Project context
21+
MCP-->>AI: Structured information
22+
Note over AI: AI processes<br/>complete context
23+
AI-->>Dev: Informed assistance
24+
Dev->>DC: Update context
25+
end
26+
27+
rect rgba(50, 50, 50, 0.5)
28+
Note over Dev,AI: Continuous Learning
29+
loop Project Evolution
30+
Dev->>DC: Update documentation
31+
AI->>MCP: Get fresh context
32+
MCP->>DC: Read updates
33+
DC-->>AI: Latest context
34+
end
35+
end
36+
37+
Note over Dev,AI: Project Evolution

‎.context/diagrams/project-structure.mmd‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
graph TD
2+
subgraph "Project Root"
3+
A[Your Project]
4+
B[.context/]
5+
C[.contextignore]
6+
end
7+
8+
subgraph ".context Directory"
9+
D[index.md]
10+
E[docs/]
11+
F[diagrams/]
12+
end
13+
14+
subgraph "Documentation Types"
15+
G[Architecture Diagrams]
16+
H[Flow Charts]
17+
I[Sequence Diagrams]
18+
J[Reference Docs]
19+
K[Project History]
20+
L[Team Conventions]
21+
end
22+
23+
A --> B
24+
A --> C
25+
B --> D
26+
B --> E
27+
B --> F
28+
F --> G
29+
F --> H
30+
F --> I
31+
E --> J
32+
E --> K
33+
E --> L
34+
35+
style A fill:#ff9999,stroke:#000000,stroke-width:3px,color:#000000
36+
style B fill:#4444ff,stroke:#000000,stroke-width:3px,color:#ffffff
37+
style C fill:#ffffff,stroke:#000000,stroke-width:3px,color:#000000
38+
style D fill:#00cc00,stroke:#000000,stroke-width:3px,color:#000000
39+
style E fill:#4444ff,stroke:#000000,stroke-width:3px,color:#ffffff
40+
style F fill:#4444ff,stroke:#000000,stroke-width:3px,color:#ffffff
41+
style G fill:#ff4444,stroke:#000000,stroke-width:3px,color:#ffffff
42+
style H fill:#ff4444,stroke:#000000,stroke-width:3px,color:#ffffff
43+
style I fill:#ff4444,stroke:#000000,stroke-width:3px,color:#ffffff
44+
style J fill:#00cc00,stroke:#000000,stroke-width:3px,color:#000000
45+
style K fill:#00cc00,stroke:#000000,stroke-width:3px,color:#000000
46+
style L fill:#00cc00,stroke:#000000,stroke-width:3px,color:#000000
47+
48+
linkStyle default stroke:#000000,stroke-width:2px

‎README.md‎

Lines changed: 117 additions & 63 deletions
Original file line numberDiff line numberDiff line change
@@ -1,48 +1,78 @@
1-
# dotcontext
1+
# dotcontext 📚
2+
[![npm version](https://badge.fury.io/js/dotcontext.svg)](https://badge.fury.io/js/dotcontext)
23

3-
A convention developers can all easily adopt to capture and communicate the context of your codebase for both AI coding agents and humans. Similar to .env and .editorconfig, but focused on documenting your code. Visit [codebasecontext.org](https://codebasecontext.org/) to learn more about the specification.
4+
AI coding has evolved from simple file-level completions to sophisticated project-wide assistance. As these tools become more capable, they need more context - not just about individual files, but about your project's architecture, history, and design decisions.
45

5-
## Overview
6+
dotcontext emerged from a common pattern: developers repeatedly sharing README files with AI assistants to help them understand projects before starting tasks. We've standardized this approach into a structured system that helps AI coding agents grasp your codebase's full context from the start.
67

7-
This package provides a comprehensive system for managing and leveraging codebase context through two main components:
8-
9-
1. **CLI Tool (`dotcontext`)**: A command-line interface that helps developers:
10-
- Initialize and structure context documentation
11-
- Validate context files against the CCS specification
12-
- Generate and manage architectural diagrams
13-
- Maintain consistent documentation standards
14-
- Lint context files for best practices
8+
![Codebase Context](https://raw.githubusercontent.com/Agentic-Insights/codebase-context-spec/main/img/codebase-context.png)
159

16-
2. **MCP Server (`dotcontext-mcp`)**: An integration layer that enables AI tools to understand your codebase by:
17-
- Providing programmatic access to context information
18-
- Exposing architectural diagrams and documentation
19-
- Enabling automated context validation
20-
- Supporting tools like [Cline](https://codebasecontext.org/tools/code-generation/cline) in making informed decisions about your code
10+
```mermaid
11+
%%{init: { 'theme': 'dark' } }%%
12+
sequenceDiagram
13+
participant Dev as Developer
14+
participant DC as .context/
15+
participant MCP as MCP Server
16+
participant AI as AI Assistant
17+
18+
rect rgba(50, 50, 50, 0.5)
19+
Note over Dev,AI: Initial Setup
20+
Dev->>DC: Create context structure
21+
Dev->>DC: Add documentation
22+
Dev->>DC: Create diagrams
23+
end
24+
25+
rect rgba(50, 50, 50, 0.5)
26+
Note over Dev,AI: Development Flow
27+
Dev->>AI: Start new task
28+
AI->>MCP: Request context
29+
MCP->>DC: Read context
30+
DC-->>MCP: Project context
31+
MCP-->>AI: Structured information
32+
Note over AI: AI processes<br/>complete context
33+
AI-->>Dev: Informed assistance
34+
Dev->>DC: Update context
35+
end
36+
37+
rect rgba(50, 50, 50, 0.5)
38+
Note over Dev,AI: Continuous Learning
39+
loop Project Evolution
40+
Dev->>DC: Update documentation
41+
AI->>MCP: Get fresh context
42+
MCP->>DC: Read updates
43+
DC-->>AI: Latest context
44+
end
45+
end
46+
47+
Note over Dev,AI: Project Evolution
48+
```
2149

22-
Together, these components create a bridge between human-readable documentation and machine-interpretable context, making your codebase more accessible to both developers and AI tools.
23-
![Codebase Context](https://raw.githubusercontent.com/Agentic-Insights/codebase-context-spec/main/img/codebase-context.png)
50+
## What is Model Context Protocol (MCP)? 🤔
2451

25-
## Usage
52+
MCP is a communication standard that lets AI Coding Agents understand your codebase better. Think of it like a translator between your documentation and AI assistants. When an AI tool supports MCP, it can:
2653

27-
### CLI Quick Start
54+
- Read and understand your project's documentation
55+
- Parse architectural diagrams
56+
- Make informed suggestions about your code
57+
- Validate documentation structure
2858

29-
The CLI tool provides direct command-line access to context management features:
59+
## Quick Start 🚀
3060

61+
### 1. Install and Initialize
3162
```bash
32-
# Initialize a new context directory
63+
# Navigate to your project root
64+
cd your-project
65+
66+
# Create your first context directory
3367
npx dotcontext init
3468

3569
# Validate your context structure
3670
npx dotcontext validate
37-
38-
# View available diagrams
39-
npx dotcontext diagrams --content
4071
```
4172

42-
### MCP Integration
43-
44-
Enable AI tools to understand your codebase by adding the MCP server to your client's configuration:
73+
### 2. Configure MCP Server 🔌
4574

75+
#### For most environments:
4676
```json
4777
{
4878
"mcpServers": {
@@ -56,8 +86,7 @@ Enable AI tools to understand your codebase by adding the MCP server to your cli
5686
}
5787
```
5888

59-
For Windows users experiencing 'spawn NOENT' errors in Cline, use this configuration:
60-
89+
#### For Windows users (resolves 'spawn NOENT' errors):
6190
```json
6291
{
6392
"mcpServers": {
@@ -71,56 +100,81 @@ For Windows users experiencing 'spawn NOENT' errors in Cline, use this configura
71100
}
72101
```
73102

74-
The MCP server provides tools for AI agents to:
75-
- Read and parse your context documentation
76-
- Access architectural diagrams
77-
- Validate context structure
78-
- Extract project metadata
103+
## Features 🛠️
79104

80-
All tools automatically use the `.context` directory in your project root unless specified otherwise.
105+
### MCP Tools
106+
- `init`: Create new context directories
107+
- `validate`: Check documentation structure
108+
- 💡 `context`: Get project documentation and insights
109+
> **AI Assistant Tip**: Use this command to understand a project before starting tasks!
110+
> ```
111+
> Custom Instruction: "use dotcontext's context to understand this project before starting on your task"
112+
> ```
113+
- `diagrams`: View architectural diagrams
81114
82-
## Learn More About CCS
115+
All tools automatically work from your project root, looking for a `.context` directory.
83116
84-
- 📺 [Watch the CCS Introduction Video](https://youtu.be/6icquh4thCw)
85-
- 📄 [Read the CCS RFC on SubStack](https://agenticinsights.substack.com/p/codebase-context-specification-rfc)
86-
- 📚 [CCS GitHub Repository](https://github.com/Agentic-Insights/codebase-context-spec)
117+
### Project Structure
118+
Your `.context` directory organizes project knowledge:
119+
- `index.md`: Main entry point for AI tools
120+
- `docs/`: Documentation and references
121+
- `diagrams/`: Architectural and flow diagrams
122+
- `.contextignore`: Excludes irrelevant information
87123
88-
## Development
124+
### CLI Tools
125+
- Initialize context directories (`dotcontext init`)
126+
- Validate documentation structure (`dotcontext validate`)
127+
- List architectural diagrams (`dotcontext diagrams`)
128+
- Lint context files for consistency
89129
90-
### Setup
130+
## Common Use Cases 📋
91131
92-
1. Clone the repository
93-
2. Install dependencies:
94-
```bash
95-
npm install
96-
```
97-
3. Build the project:
98-
```bash
99-
npm run build
100-
```
101-
4. Link for local development:
102-
```bash
103-
npm link
104-
```
132+
- **Legacy Projects**: Document historical context and system changes
133+
- **Architecture Decisions**: Explain design patterns and trade-offs
134+
- **Tribal Knowledge**: Capture team conventions and practices
135+
- **Migration Notes**: Track system transitions (e.g., queue system → topic system)
105136
106-
### Testing
137+
## Technical Details ⚙️
138+
139+
- Built with TypeScript for type safety
140+
- Automated versioning via Semantic Release
141+
- Modular architecture for extensibility
142+
- Comprehensive test coverage
107143
108-
Run the test suite:
144+
## Learn More 📖
109145
146+
- 📺 [CCS Introduction Video](https://youtu.be/6icquh4thCw)
147+
- 📄 [CCS RFC on SubStack](https://agenticinsights.substack.com/p/codebase-context-specification-rfc)
148+
- 📚 [CCS GitHub Repository](https://github.com/Agentic-Insights/codebase-context-spec)
149+
- 🌐 [Official Website](https://codebasecontext.org)
150+
151+
## Development 👩‍💻
152+
153+
### Setup
110154
```bash
111-
npm test
112-
```
155+
# Install dependencies
156+
npm install
113157
114-
Run tests with coverage:
158+
# Build project
159+
npm run build
115160
161+
# Link for local development
162+
npm link
163+
```
164+
165+
### Testing
116166
```bash
167+
# Run tests
168+
npm test
169+
170+
# Run with coverage
117171
npm run test:coverage
118172
```
119173

120-
## Contributing
174+
## Contributing 🤝
121175

122-
Contributions are welcome! Please ensure you follow our contribution guidelines and maintain test coverage for new features.
176+
We welcome contributions! Please check our contribution guidelines and maintain test coverage for new features.
123177

124-
## License
178+
## License 📄
125179

126180
MIT

0 commit comments

Comments
 (0)