Skip to content

Commit 4b96c74

Browse files
devkanroCopilot
devkanro
and
Copilot
authored
docs: overhaul documentation structure and add design documents (#291)
* refactor: consolidate workflow files into .github/ Migrate skills from .copilot/skills/ to .github/skills/ (SKILL.md agent spec). Move brainstorm.md, docmap.md, instructions to .github/. Add branch creation step to brainstorm workflow. Update all internal references. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * docs: overhaul documentation structure and add design docs Reorganize docs by reader journey (overview → architecture → design/): - Add docs/overview.md: plugin introduction and key concepts - Add docs/getting-started.md + docs/contributing.md (split from development.md) - Simplify architecture.md to high-level layer overview with links to design docs - Add docs/README.md as documentation navigation page Add 8 why-first design documents under docs/design/: - psi-and-mixin.md: mixin pattern rationale, feature interfaces - symbol-resolution.md: two-phase resolve, scope hierarchy, root providers - stub-indexing.md: stub design tradeoffs, index types, external data - annotation-system.md: per-version annotators, validation philosophy - code-completion.md: provider-per-context model, insert handlers - compiler-system.md: in-process compiler rationale, plugin architecture - prototext.md: separate language design, schema linking - editions.md: feature-set model, migration from syntax versions Overhaul README.md: visual layout, feature highlights, Copilot workflow section. Add .intellijPlatform to .gitignore. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * chore: complete brainstorm, update ship skill with PR creation Mark brainstorm/docs-internals as Completed. Update ship skill: final step is now PR creation (or push if PR exists). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 26426c9 commit 4b96c74

24 files changed

Lines changed: 1820 additions & 427 deletions

‎.copilot/docmap.md‎

Lines changed: 0 additions & 55 deletions
This file was deleted.

‎.github/brainstorm.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
---
2+
status: Completed
3+
created: 2026-03-09
4+
updated: 2026-03-09
5+
paused_from:
6+
---
7+
8+
# Feature: Documentation Overhaul — Structure, Design Docs, and README
9+
10+
## Problem
11+
12+
The existing docs describe *what* exists and *where* — class names, file locations, feature lists. But that information is already in the code. What's missing is the *why*: why was the mixin pattern chosen for PSI elements? Why does symbol resolution have separate absolute and relative phases? Why use a custom in-process compiler instead of calling protoc? These design decisions are invisible in code but critical for making good future decisions.
13+
14+
Additionally, the current docs structure is flat and unfriendly to newcomers — opening `architecture.md` immediately throws PSI hierarchies, stub indices, and compiler internals at the reader with no gradual on-ramp.
15+
16+
The README is also bare-bones: a checklist of features with no visual appeal or project identity.
17+
18+
## Approach
19+
20+
Create design-intent documentation that answers *why*, not *what*. Each doc should:
21+
22+
- **Explain the problem** the subsystem solves and why it's non-trivial
23+
- **Describe the design choices** and what alternatives were considered or rejected
24+
- **Reveal the tradeoffs** — what was gained, what was sacrificed
25+
- **Connect decisions to constraints** — IntelliJ platform requirements, protobuf spec demands, performance needs
26+
27+
Reorganize the doc structure by reader journey (overview → architecture → design deep-dives) so newcomers aren't overwhelmed. Refresh the README for visual impact and add Copilot workflow section.
28+
29+
## Design
30+
31+
### New Documentation Structure
32+
33+
```
34+
docs/
35+
├── README.md ← Documentation index / navigation page
36+
├── overview.md ← What the plugin does, user experience, key concepts
37+
├── architecture.md ← Simplified: layer diagram + one paragraph per layer
38+
├── getting-started.md ← Dev environment setup (extracted from development.md)
39+
├── contributing.md ← How to contribute: grammar, features, modules
40+
├── extension-points.md ← Extension API reference (existing, refined)
41+
├── design/ ← Deep-dive "why" documents
42+
│ ├── psi-and-mixin.md ← Why mixin pattern? Why feature interfaces?
43+
│ ├── symbol-resolution.md ← Why two-phase resolve? Why scope hierarchy?
44+
│ ├── stub-indexing.md ← Why stubs? What tradeoffs in index design?
45+
│ ├── annotation-system.md ← Why per-version annotators? Validation philosophy
46+
│ ├── code-completion.md ← Why provider-per-context? Insert handler design
47+
│ ├── compiler-system.md ← Why in-process compiler? Plugin architecture
48+
│ ├── prototext.md ← Why separate language? Schema linking design
49+
│ └── editions.md ← Why feature-set model? Migration from syntax versions
50+
└── modules/ ← Per-module integration docs (existing, preserved)
51+
├── java.md
52+
├── go.md
53+
├── grpc.md
54+
├── aip.md
55+
└── sisyphus.md
56+
```
57+
58+
### Reader Journeys
59+
60+
- **"What does this do?"** → README → `overview.md`
61+
- **"I want to contribute"** → `getting-started.md` → `architecture.md` → `design/*`
62+
- **"I want to extend it"** → `extension-points.md` → `modules/*`
63+
- **"Why was X designed this way?"** → `design/*` directly
64+
65+
### README Overhaul
66+
67+
Redesign `README.md` at project root:
68+
69+
1. **Hero section**: Logo + one-line tagline + badges (existing) + install button/link
70+
2. **Feature highlights**: Visual cards/sections with screenshots inline, not a checklist
71+
3. **Quick start**: 3-step install guide
72+
4. **Compatibility warning**: Keep the JetBrains plugin conflict note but style it better
73+
5. **Architecture at a glance**: Simple layer diagram or feature overview image
74+
6. **Copilot workflow section**: New — explain that this project uses AI-assisted development with a structured brainstorm → implement → ship → reflect cycle. Link to `.github/copilot-instructions.md` and `.github/skills/`
75+
7. **Contributing**: Link to `docs/contributing.md`
76+
8. **Screenshots gallery**: Reorganize existing screenshots with better captions
77+
78+
### Design Doc Template
79+
80+
Each `docs/design/*.md` follows this structure:
81+
82+
```markdown
83+
# [Subsystem Name]
84+
85+
## The Problem
86+
What challenge does this subsystem address? Why isn't it trivial?
87+
88+
## Design Decisions
89+
### Decision 1: [Choice made]
90+
**Context**: What constraints or requirements drove this?
91+
**Alternatives considered**: What else could have been done?
92+
**Why this approach**: What made it the best fit?
93+
**Tradeoffs**: What was sacrificed?
94+
95+
### Decision 2: ...
96+
97+
## How It Fits Together
98+
Brief sketch of how this subsystem connects to others.
99+
(Not a code walkthrough — just enough to navigate.)
100+
101+
## Key Insight
102+
One or two sentences capturing the essential "aha" for this subsystem.
103+
```
104+
105+
## Questions
106+
107+
- [x] **Scope**: All 8 design docs + restructure + README — *decided: do it all*
108+
- [x] **Why vs. What**: Focus on design intent and rationale — *decided: why-first*
109+
- [x] **Audience**: Contributors and future-us (including AI) — *decided*
110+
- [x] **Formatting/navigation**: Fold into architecture.md, not separate docs — *decided*
111+
- [x] **Doc structure**: Progressive journey (overview → architecture → design/) — *decided*
112+
- [x] **README**: Visual refresh + Copilot workflow section — *decided*
113+
114+
## Decisions
115+
116+
1. **Why-first documentation**: Each doc focuses on design intent and rationale rather than describing current implementation. Code tells you *what*; docs tell you *why*.
117+
2. **Progressive structure**: Docs organized by reader journey — newcomers start with overview, contributors drill into design/, extenders use extension-points.
118+
3. **All 8 design docs in one pass**: Subsystems are interconnected; writing them together gives coherent coverage.
119+
4. **Audience is contributors + AI**: Not extension developers (extension-points.md already serves them).
120+
5. **Formatting/navigation merged into architecture.md**: Standard IntelliJ patterns, not enough unique "why" for standalone docs.
121+
6. **README overhaul**: Visual refresh with feature highlights, quick start, and Copilot workflow section.
122+
123+
## Tasks
124+
125+
(Populated when entering Implementing state)
126+
127+
## Discussion Log
128+
129+
### Round 1 — 2026-03-09
130+
**Topic**: Initial brainstorm — what documentation to create
131+
**Key points**:
132+
- Codebase analysis identified 10 major subsystems, of which 7+ have thin/missing documentation
133+
- Existing docs cover the "what" well but lack the "how"
134+
- Proposed 8 new docs organized under `docs/internals/` in 3 priority tiers
135+
**Outcome**: Proposed plan needs user input on scope, depth, and audience
136+
137+
### Round 2 — 2026-03-09
138+
**Topic**: Documentation philosophy — why vs. what
139+
**Key points**:
140+
- User pointed out docs should explain *why* (design intent) not *what* (current implementation)
141+
- "What" is already in the code; "why" is the invisible knowledge that gets lost
142+
- Docs become more stable across refactors because rationale outlives implementation
143+
**Outcome**: Decided on why-first approach
144+
145+
### Round 3 — 2026-03-09
146+
**Topic**: Scope, audience, and open questions
147+
**Key points**:
148+
- All 8 docs in one pass (subsystems are interconnected)
149+
- Audience: contributors + future-us/AI (extension-points.md already serves extenders)
150+
- Formatting/navigation: merge into architecture.md (standard IntelliJ patterns)
151+
- Renamed `internals/` to `design/` to match why-first philosophy
152+
**Outcome**: All open questions resolved
153+
154+
### Round 4 — 2026-03-09
155+
**Topic**: Documentation structure reorganization + README
156+
**Key points**:
157+
- Current flat structure is unfriendly to newcomers
158+
- Reorganize by reader journey: overview → architecture → design/
159+
- Split development.md into getting-started.md + contributing.md
160+
- README needs visual refresh: feature highlights instead of checklist, quick start, screenshots inline
161+
- Add Copilot workflow section to README explaining brainstorm → implement → ship → reflect cycle
162+
**Outcome**: Full scope finalized — ready to implement

.copilot/instructions.md renamed to .github/copilot-instructions.md

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -13,29 +13,29 @@ brainstorm → implement → ship → reflect
1313

1414
Every non-trivial change follows this cycle:
1515

16-
1. **Brainstorm** — Design the solution in `.copilot/brainstorm.md` before writing code. The brainstorm skill manages a state machine (Planning → Questioning → Ready → Implementing → Completed) that prevents premature coding.
16+
1. **Brainstorm** — Design the solution in `.github/brainstorm.md` before writing code. The brainstorm skill manages a state machine (Planning → Questioning → Ready → Implementing → Completed) that prevents premature coding.
1717

1818
2. **Implement** — Write code only after the brainstorm reaches `Implementing` state. Use todos to track progress.
1919

2020
3. **Ship** — Use the ship skill (not raw git commands) to commit and push. It enforces build verification, test execution, and brainstorm status checks before allowing a commit.
2121

22-
4. **Reflect** — After every ship, reflect on what happened. Learnings are captured in `.copilot/knowledge.md` and feed back into future work.
22+
4. **Reflect** — After every ship, reflect on what happened. Learnings are captured in `.github/knowledge.md` and feed back into future work.
2323

2424
Trivial changes (bug fixes, typos, config tweaks) skip the brainstorm and go straight to ship.
2525

2626
## Key Files
2727

2828
| File | Purpose |
2929
|---|---|
30-
| `.copilot/brainstorm.md` | Active design discussion (one per branch) |
31-
| `.copilot/knowledge.md` | Accumulated learnings and patterns |
32-
| `.copilot/docmap.md` | Documentation structure and code-to-doc mapping |
33-
| `.copilot/instructions.md` | This file — workflow overview |
34-
| `.copilot/skills/` | Custom skill definitions |
30+
| `.github/brainstorm.md` | Active design discussion (one per branch) |
31+
| `.github/knowledge.md` | Accumulated learnings and patterns |
32+
| `.github/docmap.md` | Documentation structure and code-to-doc mapping |
33+
| `.github/copilot-instructions.md` | This file — workflow overview |
34+
| `.github/skills/` | Custom skill definitions |
3535

3636
## Knowledge Base
3737

38-
`.copilot/knowledge.md` is a living document that grows with each reflection. It contains:
38+
`.github/knowledge.md` is a living document that grows with each reflection. It contains:
3939

4040
- **Project Patterns** — Recurring patterns specific to this codebase
4141
- **Common Pitfalls** — Mistakes to avoid (learned the hard way)
@@ -48,15 +48,15 @@ Before starting new work, read the knowledge base. Past reflections often contai
4848

4949
| Skill | Purpose |
5050
|---|---|
51-
| `brainstorm` | Design discussions via `.copilot/brainstorm.md` state machine |
51+
| `brainstorm` | Design discussions via `.github/brainstorm.md` state machine |
5252
| `ship` | Build → test → commit → push with safety checks |
5353
| `document` | Documentation management, code-to-doc mapping |
5454
| `reflect` | Post-ship reflection, knowledge base maintenance |
5555

5656
## Rules
5757

58-
1. **No code changes during design** — Until brainstorm reaches `Implementing`, only `.copilot/brainstorm.md` may be modified
59-
2. **Always ship through the skill** — Don't use raw git commands for committing; the ship skill enforces quality gates
58+
1. **No code changes during design** — Until brainstorm reaches `Implementing`, only `.github/brainstorm.md` may be modified
59+
2. **Always ship through the ship workflow** — Don't use raw git commands for committing; the ship skill enforces quality gates
6060
3. **Reflect after every ship** — Even quick fixes deserve a brief reflection
61-
4. **Ask before changing skills** — The reflect skill may propose workflow improvements, but always gets user approval first
62-
5. **Keep knowledge current** — Update `.copilot/knowledge.md` after each reflection, curate patterns when they recur
61+
4. **Ask before changing skills** — The reflect workflow may propose workflow improvements, but always gets user approval first
62+
5. **Keep knowledge current** — Update `.github/knowledge.md` after each reflection, curate patterns when they recur

‎.github/docmap.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
updated: 2026-03-09
3+
---
4+
5+
# Documentation Map
6+
7+
## Files
8+
9+
| File | Purpose | Related Code |
10+
|---|---|---|
11+
| README.md | Project overview, features, install, Copilot workflow | — |
12+
| CHANGELOG.md | Version history, release notes | All changes |
13+
| docs/README.md | Documentation index / navigation page | — |
14+
| docs/overview.md | What the plugin does, key concepts | — |
15+
| docs/architecture.md | High-level layer diagram, subsystem overview | All `src/main/kotlin/` |
16+
| docs/getting-started.md | Build, run, test guide | build.gradle.kts, gradle.properties, .github/workflows/ |
17+
| docs/contributing.md | Code style, adding features/modules, Copilot workflow | lang/, META-INF/ |
18+
| docs/extension-points.md | Custom extension point API docs | lang/root/, lang/psi/feature/, compile/ |
19+
| docs/design/psi-and-mixin.md | Why mixin pattern for PSI elements | lang/psi/, lang/psi/proto/mixin/, lang/psi/feature/ |
20+
| docs/design/symbol-resolution.md | Why two-phase resolve, scope hierarchy | lang/psi/proto/ProtobufSymbolResolver, lang/psi/proto/ProtobufScope, lang/root/ |
21+
| docs/design/stub-indexing.md | Why stubs, index design tradeoffs | lang/psi/stub/, lang/psi/stub/type/, lang/psi/stub/index/ |
22+
| docs/design/annotation-system.md | Why per-version annotators, validation philosophy | lang/annotator/, lang/quickfix/ |
23+
| docs/design/code-completion.md | Why provider-per-context, insert handlers | lang/completion/ |
24+
| docs/design/compiler-system.md | Why in-process compiler, plugin architecture | compile/ |
25+
| docs/design/prototext.md | Why separate language for text format | lang/psi/text/, prototext.bnf |
26+
| docs/design/editions.md | Why feature-set model for editions | lang/psi/feature/ProtobufFeature, lang/annotator/ProtobufEditionAnnotator |
27+
| docs/modules/java.md | Java integration module | java/ |
28+
| docs/modules/go.md | Go integration module | golang/ |
29+
| docs/modules/grpc.md | gRPC and microservices modules | grpc/, microservices/ |
30+
| docs/modules/aip.md | AIP spec support module | aip/ |
31+
| docs/modules/sisyphus.md | Sisyphus framework integration | sisyphus/ |

0 commit comments

Comments
 (0)