Skip to content

ci: add markdownlint workflow + fix READMEs #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
valorisa merged 1 commit into from
Jun 23, 2026
Merged

ci: add markdownlint workflow + fix READMEs #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 28 additions & 0 deletions .github/workflows/markdownlint.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,28 @@
name: Markdown Lint

on:
push:
branches:
- master
paths:
- '**.md'
pull_request:
branches:
- master
paths:
- '**.md'

jobs:
markdownlint:
name: Lint Markdown files
runs-on: ubuntu-latest

steps:
- name: Checkout repository
uses: actions/checkout@v4

- name: Run markdownlint
uses: DavidAnson/markdownlint-cli2-action@v17
with:
globs: '**/*.md'
config: '.markdownlint.json'
9 changes: 9 additions & 0 deletions .markdownlint.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
{
"default": true,
"MD013": { "line_length": 120 },
"MD029": { "style": "ordered" },
"MD033": false,
"MD036": false,
"MD041": false,
"MD060": false
}
131 changes: 88 additions & 43 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,10 @@ But every single time, you waste precious minutes:
This framework is the answer.

> 💡 **What is an AI assistant, for beginners?**
> An AI assistant (like ChatGPT or Claude) is a software tool you can write to in plain language. You ask it a question or give it a task, and it generates a text response. Think of it as a very fast, very well-read writing partner — but one with no memory of you, no knowledge of your style, and a tendency to sound corporate by default. This framework fixes that.
> An AI assistant (like ChatGPT or Claude) is a software tool you can write to in plain language. You ask it a question
> or give it a task, and it generates a text response. Think of it as a very fast, very well-read writing partner — but
> one with no memory of you, no knowledge of your style, and a tendency to sound corporate by default. This framework
> fixes that.

It gives you a **ready-to-use method** to:

Expand All @@ -30,7 +33,8 @@ It gives you a **ready-to-use method** to:
3. **Maintain quality over time** (preventing the AI from drifting toward generic language),
4. **Fix mistakes** in a few minutes per month.

The result: a **digital assistant** that produces texts ready to send (or needing less than 2 minutes of touch-up), 100% in your style.
The result: a **digital assistant** that produces texts ready to send (or needing less than 2 minutes of touch-up), 100%
in your style.

---

Expand All @@ -42,36 +46,44 @@ The result: a **digital assistant** that produces texts ready to send (or needin
- **Anyone** who uses AI and is tired of generic, robotic responses.

**No technical skills required.**
All you need is an account on an AI platform that supports the "Project" feature (Claude Pro or ChatGPT Plus), and about thirty of your own texts.
All you need is an account on an AI platform that supports the "Project" feature (Claude Pro or ChatGPT Plus), and about
thirty of your own texts.

> 💡 **What is a "Project" feature?**
> Some AI platforms let you create a dedicated workspace called a "Project" (or similar). Inside this workspace, you can set permanent instructions that the AI will follow for every conversation — without you having to repeat them each time. Think of it as a "briefing sheet" permanently attached to your AI's memory. Claude Pro calls this "Projects"; ChatGPT Plus calls it "Custom Instructions" or "Projects" depending on the version.
> Some AI platforms let you create a dedicated workspace called a "Project" (or similar). Inside this workspace, you can
> set permanent instructions that the AI will follow for every conversation — without you having to repeat them each
> time. Think of it as a "briefing sheet" permanently attached to your AI's memory. Claude Pro calls this "Projects";
> ChatGPT Plus calls it "Custom Instructions" or "Projects" depending on the version.

---

## 🧭 What you'll find in this repository

> 💡 **What is a repository?**
> A repository (often called a "repo") is a folder hosted on GitHub that contains all the files for a project. GitHub is a website where developers (and increasingly non-developers) store, share, and collaborate on files. Think of it as a Google Drive, but built for code and text files, with version history included.

| File / Folder | What it contains |
| ------------------------------------ | ------------------------------------------------------------------------------------------- |
| `templates/Prompt_Master.md` | The **Constitution**: the rules that govern your assistant (style, tone, forbidden phrases) |
| `templates/Meta-Prompt_Nettoyage.md` | The recipe to sort your texts and extract the 7 best examples |
| `templates/Golden_Dataset.md` | The **5 regression tests** to verify every month that the AI hasn't drifted |
| `templates/Quarantaine.md` | The file to log the AI's daily mistakes (zero friction) |
| `templates/Changelog.md` | The change log (to keep track of your configuration updates) |
| `docs/` | Complementary guides (glossary, quick start, architecture) |
| `examples/` | Concrete examples of emails and posts |
> A repository (often called a "repo") is a folder hosted on GitHub that contains all the files for a project. GitHub is
> a website where developers (and increasingly non-developers) store, share, and collaborate on files. Think of it as a
> Google Drive, but built for code and text files, with version history included.

| File / Folder | What it contains |
| ------------------------------------ | -------------------------------------------------------------- |
| `templates/Prompt_Master.md` | The **Constitution**: style rules, tone, forbidden phrases |
| `templates/Meta-Prompt_Nettoyage.md` | Extracts the 7 best example texts from your collection |
| `templates/Golden_Dataset.md` | **5 regression tests** — monthly check against voice drift |
| `templates/Quarantaine.md` | Daily log of AI mistakes (zero friction, copy-paste only) |
| `templates/Changelog.md` | Change log — tracks every configuration update with dates |
| `docs/` | Complementary guides (glossary, quick start, architecture) |
| `examples/` | Concrete examples of emails and posts |

> 💡 **What are `.md` files?**
> Files ending in `.md` are Markdown files — plain text files with light formatting (headings, bold, bullet points). You can open them with any text editor (Notepad, VS Code, etc.) or read them directly on GitHub, where they render beautifully. No special software is required.
> Files ending in `.md` are Markdown files — plain text files with light formatting (headings, bold, bullet points). You
> can open them with any text editor (Notepad, VS Code, etc.) or read them directly on GitHub, where they render
> beautifully. No special software is required.

---

### 📂 Full folder structure

```
```text
📂 custom-ai-assistant-framework/
├── 📄 README.md
├── 📄 LICENSE
Expand All @@ -88,7 +100,7 @@ All you need is an account on an AI platform that supports the "Project" feature
├── 📄 Meta-Prompt_Nettoyage.md
├── 📄 Prompt_Master.md
└── 📄 Quarantaine.md
```
```text

---

Expand All @@ -99,7 +111,8 @@ All you need is an account on an AI platform that supports the "Project" feature
- **Recommended**: [Claude Pro](https://claude.ai) (the most advanced "Projects" interface).
- **Alternative**: ChatGPT Plus ("Projects" or "Custom Instructions" feature).

> 💡 Both platforms require a paid subscription (approximately $20/month). Free plans exist but do not include the persistent "Project" feature, which is essential for this framework to work.
> 💡 Both platforms require a paid subscription (approximately $20/month). Free plans exist but do not include the
> persistent "Project" feature, which is essential for this framework to work.

---

Expand All @@ -111,7 +124,9 @@ All you need is an account on an AI platform that supports the "Project" feature
- Paste them all into a single text file, one block per text, separated by blank lines or numbered.

> 💡 **Why 30 texts?**
> The AI needs enough examples to identify the patterns in *your* writing — your sentence length, your preferred transitions, your vocabulary, your level of formality. Ten texts is too few; a hundred is overkill. Thirty is the practical sweet spot that gives the AI enough material to work with without overwhelming it.
> The AI needs enough examples to identify the patterns in *your* writing — your sentence length, your preferred
> transitions, your vocabulary, your level of formality. Ten texts is too few; a hundred is overkill. Thirty is the
> practical sweet spot that gives the AI enough material to work with without overwhelming it.

---

Expand All @@ -120,20 +135,28 @@ All you need is an account on an AI platform that supports the "Project" feature
- Open `templates/Meta-Prompt_Nettoyage.md`.
- Copy its entire content.
- In the AI, start a new conversation, **paste this prompt**, then **attach your file of 30–50 texts**.
- The AI will select the 7 texts most representative of your voice, and for each one generate a **Stylistic Identity Card** (DNA + Anti-patterns).
- The AI will select the 7 texts most representative of your voice, and for each one generate a **Stylistic Identity
Card** (DNA + Anti-patterns).
- Save the result in a file called `Exemples.md`. **This is your Case Law.**

> 💡 **What is a "prompt"?**
> A prompt is simply the instruction or question you give to an AI. It can be one sentence ("Write me a sales email") or a very detailed document (like the templates in this framework). The more precise and structured the prompt, the more predictable and useful the AI's response.

> A prompt is simply the instruction or question you give to an AI. It can be one sentence ("Write me a sales email") or
> a very detailed document (like the templates in this framework). The more precise and structured the prompt, the more
> predictable and useful the AI's response.
>
> 💡 **What is a "Stylistic Identity Card"?**
> When the AI analyzes your texts, it produces a short profile of each one: what makes it sound like *you* (your "DNA" — recurring phrases, rhythm, tone) and what to avoid ("Anti-patterns" — things that would signal the text was written by someone else or by a generic AI). Think of it as a writing fingerprint.

> When the AI analyzes your texts, it produces a short profile of each one: what makes it sound like *you* (your "DNA" —
> recurring phrases, rhythm, tone) and what to avoid ("Anti-patterns" — things that would signal the text was written by
> someone else or by a generic AI). Think of it as a writing fingerprint.
>
> 💡 **What is "Case Law"?**
> This metaphor borrows from law: just as judges refer to past rulings to ensure consistency, your AI will refer to your best example texts to ensure all future outputs stay consistent with your voice. Your `Exemples.md` file acts as the precedents.

> This metaphor borrows from law: just as judges refer to past rulings to ensure consistency, your AI will refer to your
> best example texts to ensure all future outputs stay consistent with your voice. Your `Exemples.md` file acts as the
> precedents.
>
> 💡 **How do you "attach a file" to an AI?**
> Most AI platforms with a "Project" or chat interface have a paperclip icon or an "Upload" button that lets you attach a file to your message. The AI will read its contents and use them as context for its response.
> Most AI platforms with a "Project" or chat interface have a paperclip icon or an "Upload" button that lets you attach
> a file to your message. The AI will read its contents and use them as context for its response.

---

Expand All @@ -147,7 +170,9 @@ All you need is an account on an AI platform that supports the "Project" feature
- Save this personalized file.

> 💡 **Why call it a "Constitution"?**
> Just like a country's constitution is the supreme document that all laws must respect, your `Prompt_Master.md` is the supreme document that governs everything your AI says. Every response it generates will be filtered through these rules. It's the single most important file in the whole framework.
> Just like a country's constitution is the supreme document that all laws must respect, your `Prompt_Master.md` is the
> supreme document that governs everything your AI says. Every response it generates will be filtered through these
> rules. It's the single most important file in the whole framework.

---

Expand All @@ -159,10 +184,15 @@ All you need is an account on an AI platform that supports the "Project" feature
- **You're done!** Start asking questions. The AI will respond in your voice.

> 💡 **What are "system instructions"?**
> System instructions are a special field in a Project where you write instructions that the AI silently applies to every single conversation within that project — without you having to repeat them. It's the invisible briefing that runs in the background at all times. This is fundamentally different from typing instructions in a normal chat message.

> System instructions are a special field in a Project where you write instructions that the AI silently applies to
> every single conversation within that project — without you having to repeat them. It's the invisible briefing that
> runs in the background at all times. This is fundamentally different from typing instructions in a normal chat
> message.
>
> 💡 **What is a "knowledge base"?**
> In Claude's Projects interface, the knowledge base is a document storage area where you upload reference files. The AI can access these files during any conversation in the project, as if they were always open on its desk. This is where you put your `Exemples.md` so the AI always has your writing samples at hand.
> In Claude's Projects interface, the knowledge base is a document storage area where you upload reference files. The AI
> can access these files during any conversation in the project, as if they were always open on its desk. This is where
> you put your `Exemples.md` so the AI always has your writing samples at hand.

---

Expand All @@ -176,10 +206,14 @@ To make sure your assistant stays faithful over time — AI platforms update sil
- If a test fails, adjust your Master Prompt or your Examples (see `docs/guide-de-demarrage.md`).

> 💡 **What is a "regression test"?**
> In software development, a regression test checks that something which used to work still works after a change. Here, the idea is the same: once a month, you run 5 specific writing scenarios through your AI to verify it still sounds like you. If it starts sounding generic or corporate again, you know the configuration needs a tune-up.

> In software development, a regression test checks that something which used to work still works after a change. Here,
> the idea is the same: once a month, you run 5 specific writing scenarios through your AI to verify it still sounds
> like you. If it starts sounding generic or corporate again, you know the configuration needs a tune-up.
>
> 💡 **What does "AI drift" mean?**
> AI platforms are updated regularly by their developers. These updates can subtly change how the AI interprets instructions, which may cause it to gradually sound less like you and more generic. "Drift" is this slow, silent deviation from your intended voice. The monthly test is your early-warning system.
> AI platforms are updated regularly by their developers. These updates can subtly change how the AI interprets
> instructions, which may cause it to gradually sound less like you and more generic. "Drift" is this slow, silent
> deviation from your intended voice. The monthly test is your early-warning system.

---

Expand All @@ -189,14 +223,19 @@ It will happen occasionally. Here's what to do:

- **Correct the text manually** before sending it (professional standards apply).
- **Copy-paste** the failed prompt and response into `Quarantaine.md` (on your local computer).
- At the end of the month, run a **"Doctor session"**: give the AI your `Quarantaine.md` file and ask it to identify the 3 changes to make to your configuration.
- At the end of the month, run a **"Doctor session"**: give the AI your `Quarantaine.md` file and ask it to identify the
3 changes to make to your configuration.
- Log those changes in `Changelog.md` and update your files accordingly.

> 💡 **What is a "Quarantine" file?**
> It's a simple running log where you paste examples of the AI's mistakes — like a notepad for bugs. Zero friction: no formatting required, just copy-paste. At the end of the month, this raw collection of failures becomes the input for a structured improvement session. The AI itself helps you diagnose what went wrong and how to fix it.

> It's a simple running log where you paste examples of the AI's mistakes — like a notepad for bugs. Zero friction: no
> formatting required, just copy-paste. At the end of the month, this raw collection of failures becomes the input for a
> structured improvement session. The AI itself helps you diagnose what went wrong and how to fix it.
>
> 💡 **What is a "Changelog"?**
> A changelog is a running record of every change made to a configuration or software, with dates and descriptions. It lets you roll back if a change made things worse, and helps you remember what you tried. Think of it as a diary for your AI setup.
> A changelog is a running record of every change made to a configuration or software, with dates and descriptions. It
> lets you roll back if a change made things worse, and helps you remember what you tried. Think of it as a diary for
> your AI setup.

---

Expand All @@ -212,10 +251,13 @@ It will happen occasionally. Here's what to do:

This repository is licensed under the MIT License (see `LICENSE`).
You are free to use it, modify it, and redistribute it.
**Use it at your own risk**: this system is an assistant, not a substitute for your professional judgment. Always read texts before sending them.
**Use it at your own risk**: this system is an assistant, not a substitute for your professional judgment. Always read
texts before sending them.

> 💡 **What is an MIT license?**
> The MIT license is one of the most permissive open-source licenses. It essentially means: "Do whatever you want with this — use it, modify it, sell it — just keep the original copyright notice." It imposes almost no restrictions on the user.
> The MIT license is one of the most permissive open-source licenses. It essentially means: "Do whatever you want with
> this — use it, modify it, sell it — just keep the original copyright notice." It imposes almost no restrictions on the
> user.

---

Expand All @@ -227,10 +269,13 @@ This framework is the result of rigorous stress-testing, designed to be **pragma

## 📬 Contact

If you have questions, suggestions, or want to adapt this framework to a specific industry, feel free to open an **issue** on this repository or contact the author via GitHub ([@valorisa](https://github.com/valorisa)).
If you have questions, suggestions, or want to adapt this framework to a specific industry, feel free to open an
**issue** on this repository or contact the author via GitHub ([@valorisa](https://github.com/valorisa)).

> 💡 **What is an "issue" on GitHub?**
> An issue is a comment thread attached to a repository. It's the standard way to report a bug, ask a question, or suggest a feature. You need a (free) GitHub account to open one. Think of it as a public forum attached directly to the project.
> An issue is a comment thread attached to a repository. It's the standard way to report a bug, ask a question, or
> suggest a feature. You need a (free) GitHub account to open one. Think of it as a public forum attached directly to
> the project.

---

Expand Down
Loading
Loading