Skip to content

Commit 955c27a

Browse files
AdrianRomanskiAdrianRomanski
committed
refactor: update internal wiki README with new rules from skill
1 parent f164ccc commit 955c27a

4 files changed

Lines changed: 145 additions & 135 deletions

File tree

‎.gemini/skills/readme-generator/skill.md‎

Lines changed: 101 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -20,16 +20,25 @@ Use this skill whenever asked to generate or refactor a `README.md` file anywher
2020
- Describe real-world domain responsibilities, system architecture, visual encodings, visual/UX flows, and business capabilities.
2121
- Write for human engineers joining the project who need to grasp the conceptual purpose immediately.
2222

23-
### 2. 🚫 STAGE-1 ANTI-PATTERNS (STRICTLY PROHIBITED)
23+
### 2. 👋 Warm & Inviting Entry Point (Main Repository README)
24+
- The root `README.md` serves as the primary entrance and front door to the repository.
25+
- Provide a friendly, approachable welcome that introduces what the repository is about, its mission, core stack, how to use it, and how to get started in minutes without drowning the reader in jargon upfront.
26+
27+
### 3. 🚫 STAGE-1 ANTI-PATTERNS (STRICTLY PROHIBITED)
2428
- **NO Dry Public API Dumps**: Do NOT list raw interface field-by-field definitions (`interface Foo { bar: string; baz: number }`), type aliases, or function signatures with parameter lists.
2529
- **NO Robotic Boilerplate Usage Snippets**: Do NOT paste generic copy-pasted TypeScript import/usage blocks (`import { X } from './x'; const x = new X();`) unless explaining a critical integration flow.
2630
- **NO Line-by-Line Code Trivia**: Avoid mentioning trivial implementation mechanics or line counts.
2731
- **NO Redundant Application Inner READMEs**: Every application has **EXACTLY ONE** application README at `apps/[app-name]/README.md`. NEVER create redundant inner `src/app/README.md` or `src/README.md` files right below an application root.
2832

29-
### 3. 🔗 Mandatory Relative Paths
33+
### 4. 🔗 Mandatory Relative Paths
3034
- All links in file summaries, module tables, and architecture sections **MUST** use relative Markdown paths (e.g., [`./file-name.ts`](./file-name.ts) or [`./subfolder/README.md`](./subfolder/README.md)).
3135
- **NEVER** use absolute `file://` URLs in generated README files.
3236

37+
### 5. 📜 Schema Specification vs. Directory README (Separation of Concerns)
38+
- **Schema Specification (`WIKI_SCHEMA.md` / `[SYSTEM]_SCHEMA.md`)**: When a subsystem or knowledge base has a dedicated schema specification document, that file serves as the **Single Source of Truth (SSOT)** for strict frontmatter schemas, field validation rules, naming conventions, and automated workflow triggers (for AI agents & CLI tools).
39+
- **Directory README (`wiki/README.md`)**: Subfolder README files act as **lightweight entry points and human navigation guides**. They must **NOT** duplicate detailed schema specifications, workflow rules, or field-by-field validation contracts. Instead, they provide high-level folder structure, usage/search examples, and link directly to the schema specification (`WIKI_SCHEMA.md`).
40+
- **Title-Based WikiLink Rules**: In wiki/knowledge-base documentation, always enforce title-based WikiLink syntax (`[[Page Title]]`) rather than filename slugs (`[[page-slug]]`) to prevent ghost nodes in graph visualizers (e.g. Obsidian).
41+
3342
---
3443

3544
## 📐 README Types & Templates
@@ -40,52 +49,75 @@ Identify which type of README you are generating and follow its dedicated templa
4049

4150
### Type 1: Repository README (`README.md` at root)
4251

43-
Used for the top-level repository or monorepo root documentation.
52+
Used for the top-level repository or monorepo root documentation. Acts as a **warm welcome**, explaining the repository's purpose, workspace organization, and how to run and use it.
4453

4554
```markdown
4655
# [Repository Name]
4756

48-
[1-2 sentences summarizing the overarching mission, technology stack, and core capability of this repository.]
57+
👋 **Welcome to [Repository Name]!**
58+
59+
[Friendly 2-3 sentence welcome introducing the repository, its mission, key capabilities, and underlying technology stack in clear, accessible language.]
4960

5061
---
5162

52-
## 🌟 Capabilities & System Mission
63+
## 💡 What is this Repository About?
5364

54-
- **[Core Capability 1]**: [High-level explanation of what this repository accomplishes]
55-
- **[Core Capability 2]**: [High-level explanation of second core capability]
65+
[A clear, engaging explanation of what the repository does, the primary problems it solves, and why it exists. Written so anyone joining the project can immediately grasp the domain and vision.]
66+
67+
### Key Highlights
68+
- **[Highlight 1]**: [Short description of core feature or architecture pillar]
69+
- **[Highlight 2]**: [Short description of core feature or architecture pillar]
70+
- **[Highlight 3]**: [Short description of core feature or architecture pillar]
5671

5772
---
5873

5974
## 🏗️ Architecture & Project Structure
6075

61-
[Brief overview of the monorepo design, clean architecture layers, or workspace organisation.]
76+
[Overview of the workspace structure, monorepo layout, and key boundaries.]
6277

6378
```text
6479
[ASCII / Mermaid Architectural Diagram showing applications, libraries, and external integrations]
6580
```
6681

67-
| Layer / Workspace Area | Location | Purpose & Role |
82+
| Workspace Area / Layer | Location | Purpose & Role |
6883
| --- | --- | --- |
69-
| **Applications** | [`./apps/`](./apps/) | Standalone executables, web applications, and CLI tools. |
70-
| **Libraries** | [`./libs/`](./libs/) | Reusable domain models, application use cases, and infrastructure adapters. |
71-
| **Knowledge Base** | [`./wiki/`](./wiki/) | Structured entities, concepts, and research documentation. |
84+
| **Applications** | [`./apps/`](./apps/) | Standalone web applications, CLI tools, and demo targets. |
85+
| **Libraries** | [`./libs/`](./libs/) | Reusable domain models, UI components, application logic, and infrastructure adapters. |
86+
| **Knowledge Base / Wiki** | [`./wiki/`](./wiki/) | Structured knowledge base containing entities, concepts, and research sources. |
7287

7388
---
7489

75-
## 🚀 Getting Started & Dev Commands
90+
## 🚀 How to Use & Get Started
91+
92+
[Quick, step-by-step guide for getting up and running locally.]
93+
94+
### Prerequisites
95+
- Node.js (v18+ recommended)
96+
- npm / pnpm / yarn
97+
98+
### Quick Start Commands
99+
```bash
100+
# 1. Install dependencies
101+
npm install
102+
103+
# 2. Start the primary local application
104+
npx nx serve [app-name]
105+
```
76106

77-
| Nx Target / Script | Purpose | Command |
107+
### Essential Dev Commands
108+
| Nx Target / Script | Command | Description |
78109
| --- | --- | --- |
79-
| `serve` | Launches primary local dev application | `npx nx serve [app-name]` |
80-
| `build` | Compiles production application bundles | `npx nx run-many -t build` |
81-
| `test` | Runs test suites across the repository | `npx nx run-many -t test` |
110+
| `serve` | `npx nx serve [app-name]` | Launches dev server with live reload |
111+
| `build` | `npx nx run-many -t build` | Compiles production build artifacts across the workspace |
112+
| `test` | `npx nx run-many -t test` | Executes unit and integration test suites |
82113

83114
---
84115

85-
## 🔄 Core System Workflows
116+
## 🔄 Common Workflows & Navigation
86117

87-
1. **[Workflow Step 1 Name]**: [Explanation of workflow]
88-
2. **[Workflow Step 2 Name]**: [Explanation of workflow]
118+
1. **Exploring Applications**: Head over to [`./apps/`](./apps/) to see executable applications and UI entry points.
119+
2. **Developing Libraries**: Check out [`./libs/`](./libs/) for modular components and business logic.
120+
3. **Research & Wiki**: Browse [`./wiki/`](./wiki/) for architectural concepts, research notes, and domain documentation.
89121
```
90122

91123
---
@@ -223,10 +255,56 @@ Used for specific internal subdirectories (e.g. `components`, `services`, `d3`,
223255

224256
---
225257

258+
### Type 5: Knowledge Base / Subsystem Directory README (`wiki/README.md`)
259+
260+
Used for knowledge base root folders, structured vault directories, or subsystems governed by a separate schema specification file (e.g., `WIKI_SCHEMA.md`).
261+
262+
```markdown
263+
# [Knowledge Base / Subsystem Title]
264+
265+
[1-2 sentence overview of the directory content, knowledge base purpose, or system store.]
266+
267+
---
268+
269+
## 📜 Specification & Single Source of Truth
270+
271+
> ℹ️ **System Schema Contract**: The authoritative single source of truth (SSOT) for page frontmatter requirements, strict title-based `[[WikiLink]]` conventions, and automated workflows is documented in [../WIKI_SCHEMA.md](../WIKI_SCHEMA.md).
272+
273+
---
274+
275+
## 📁 Directory Structure & Categories
276+
277+
| Folder / Category | Purpose & Content | Example Files |
278+
| --- | --- | --- |
279+
| [`./entities/`](./entities/) | Pages describing specific things (tools, APIs, libraries) | `angular-cdk.md` |
280+
| [`./concepts/`](./concepts/) | Explanations of ideas, patterns, or architecture principles | `progressive-enhancement.md` |
281+
| [`./sources/`](./sources/) | Distilled summaries of raw source documents | `wcag-guide-2024-05-10.md` |
282+
283+
---
284+
285+
## 🔗 Navigation & External Tooling
286+
287+
- **Graph & Vault Browsing**: Open directory in Obsidian or equivalent tools using `[[Page Title]]` WikiLink syntax.
288+
- **Search CLI**:
289+
```bash
290+
rg "search query" wiki/
291+
```
292+
293+
---
294+
295+
## 📖 Reference Links
296+
297+
- See [WIKI_SCHEMA.md](../WIKI_SCHEMA.md) for full schema specifications and validation rules.
298+
- See [index.md](index.md) for current top-level navigation and statistics.
299+
```
300+
301+
---
302+
226303
## 🚀 Execution Steps
227304

228-
1. **Classify Target**: Determine if the target is a Repository, Application, Library, or Module/Directory.
305+
1. **Classify Target**: Determine if the target is a Repository, Application, Library, Knowledge Base/Subsystem Directory, or Module/Directory.
229306
2. **Inspect Files**: Read the contents of the target directory to understand its true domain purpose, architectural patterns, and functional capabilities.
230307
3. **Verify App Uniqueness**: If writing an application README, verify it lives at `apps/[app-name]/README.md` and remove any redundant `src/app/README.md` or `src/README.md` files.
231-
4. **Enforce Readability Rules**: Ensure no dry interface dumps, parameter lists, or robotic usage code blocks are present.
232-
5. **Generate README**: Write `README.md` following the exact corresponding template and ensuring relative file links (`./filename.ts`).
308+
4. **Separate Schema vs README Concerns**: If a dedicated schema specification exists (e.g. `WIKI_SCHEMA.md`), ensure the subfolder `README.md` does not duplicate detailed schema rules or workflow triggers, but links directly to the schema file as SSOT.
309+
5. **Enforce Readability & Link Conventions**: Ensure no dry interface dumps or robotic usage blocks. Ensure all WikiLinks use title-based syntax (`[[Page Title]]`) and relative file links (`./filename.md`).
310+
6. **Generate README**: Write `README.md` following the exact corresponding template.

0 commit comments

Comments
 (0)