sam/pi-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Consolidate project documentation into single project-docs master skill

Browse Source
This commit is contained in:
Sam Rolfe
2026-09-18 17:07:49 +10:00
parent 074b86fe37
commit 4eb237f9b2
5 changed files with 136 additions and 405 deletions
Download Patch File Download Diff File Expand all files Collapse all files

244
skills/project-docs/SKILL.md
View File

@@ -1,120 +1,146 @@
---
name: project-docs
description: Meta-skill to initiate or update multi-platform documentation for any project across Gitea, Obsidian, Mermaid/Archify, Vikunja, and Outline. Use when starting a new project, updating codebase docs, generating portfolio-aligned READMEs, creating AI resume context, or syncing multi-platform project documentation.
version: 1.0.0
description: The single self-contained master skill for initiating or updating all project documentation across Gitea, Obsidian, Mermaid/Archify, Vikunja, and Outline. Handles technical READMEs, human portfolio notes, architecture diagrams & Archify maps, task tracking, and AI context catalogs using Simplified Technical English (ste-writing).
version: 2.0.0
---
# project-docs (Project Lifecycle & Documentation Meta-Skill)
# project-docs (Unified Project Lifecycle & Documentation Master Skill)
`project-docs` is an **orchestrator / meta-skill** for managing project documentation across human and AI channels. Instead of re-inventing diagramming or vault manipulation, it delegates specific tasks to specialized skills (`nixos-workflow`, `project-diagramming-mermaid`, `project-diagramming-archify`, `obsidian-cli`).
`project-docs` is the **single entry point** for all project documentation across your stack. You do not need to load separate diagramming or documentation skills — `project-docs` handles everything natively.
It can be enabled on any project via `nixos-workflow` (`/config-add skill project-docs`) and invoked to **initiate** or **update** project documentation.
---
## 🎯 Platform & Target Matrix
Each platform serves a specific role, audience, tone, and scope:
| Platform | Target Audience | Purpose & Tone | Key Artifacts / Requirements |
| :--- | :--- | :--- | :--- |
| **Gitea** | Technical / Resume / Portfolio | Technical documentation and repo README. **Standard Markdown style**: brief, concise, and to the point. Highlights tech stack, usage, and key tools/skills demonstrated for employment. | `README.md` (embedded Mermaid diagram, Archify links, setup/usage commands). |
| **Obsidian** | Humans / Hiring Managers / Self | **Human understanding**. Simple, clear, layperson-friendly language, brief. Highlights skills, tools, and ideas that showcase for employment while forming a usable tool for understanding things. | `<vault>/Projects/<ProjectName>.md` (simple overview, employment highlights, embedded Mermaid). |
| **Mermaid + Archify** | Architectural Visualization | High-level system architecture and flow diagrams. | `<project>/docs/<topic>.mmd`, embedded SVG/PNG in Gitea & Obsidian. Nodes link to `https://maps.lab.audasmedia.com.au/<project>/docs/`. |
| **Vikunja** | Humans | **High-level task tracking**. Simple, brief, actionable human steps (milestones, key deliverables). | Project/Board in Vikunja with top-level tasks for human execution. |
| **Outline** | AI Agents | **Deep AI context & document index**. Itemizes what is in each document in the collection so AI can inject specific files directly without searching. **Must use `ste-writing` skill** for terse, plain, slop-free text. | Outline Overview & Collection docs (Document Catalog, system config, environment vars, AI restart guide). |
---
## 🔄 Modes of Operation
When activated, `project-docs` runs in one of two modes:
### Mode 1: Initiate (New Project Bootstrap)
Scans the current directory, audits existing documentation assets, and interactively steps through each platform to establish missing docs.
### Mode 2: Update (Keep Docs in Sync)
Scans git history, recent code edits, or architectural changes, then updates affected documentation platforms to keep human and AI docs synchronized.
---
## 📋 Interactive Discovery & Confirmation Protocol
Before creating or altering any documentation asset, `project-docs` MUST **ask and confirm** each requirement with the user.
### 1. Gitea Repository
- **Check**: Is there an existing Gitea git remote or repo?
- **Ask/Confirm**: *"Most projects have a Gitea repository. Does one exist for this project, or should it be created? [Name/Location]"*
- **Action**: Ensure repository is initialized; prepare technical `README.md` with concise usage and employment skill highlights.
### 2. Obsidian Project Note
- **Check**: Does an Obsidian project note exist?
- **Ask/Confirm**: *"Should an Obsidian project note be created for human understanding and portfolio showcase? [Confirm / Vault Path / Note Name]"*
- **Action**: Create/update the note using simple, accessible language explaining the project's purpose, key skills, and tools.
### 3. Mermaid & Archify Diagram
- **Check**: Does `<project>/docs/<topic>.mmd` or rendered diagrams exist?
- **Ask/Confirm**: *"Do you want a Mermaid architecture diagram and Archify interactive map for this project? [Confirm / Topic]"*
- **Action**:
1. Delegate to `project-diagramming-mermaid` to generate source `.mmd` and render SVG/PNG.
2. Embed Mermaid in Gitea `README.md` and Obsidian note.
3. Hyperlink Mermaid nodes/components to Archify maps on `https://maps.lab.audasmedia.com.au/`.
4. Optionally delegate map publishing to `project-diagramming-archify` (`publish-maps.sh`).
### 4. Vikunja (Human Tasks)
- **Check**: Is Vikunja task tracking configured?
- **Ask/Confirm**: *"Should a Vikunja project/board be created for human task tracking? [Confirm / Name / Location]"*
- **Action**: Define simple, high-level tasks for human team members/owner to follow.
### 5. Outline (AI Context & Document Catalog)
- **Check**: Does an Outline collection or project overview exist?
- **Ask/Confirm**: *"Should an Outline document collection be created for AI agents to resume context across restarts? [Confirm / Collection Name]"*
- **Action**: Generate a terse Outline Overview that itemizes every document in the collection with its scope and path. Enforce the **`ste-writing`** skill (Simplified Technical English) so AI agents can inject exact documents without searching or parsing prose bloat.
---
## 🛠 Sub-Skill Orchestration Rules
- **`nixos-workflow`**: Used for asset management. New skill updates are pushed to Gitea (`https://gitea.lab.audasmedia.com.au/sam/pi-config`) and activated per project via `/config-add skill project-docs`.
- **`project-diagramming-mermaid`**: Triggered when generating or updating Mermaid source and image renderings under `<project>/docs/`.
- **`project-diagramming-archify`**: Triggered to build interactive HTML architecture maps and publish to `maps.lab.audasmedia.com.au`.
- **`ste-writing`**: Required for Outline AI documentation. Enforces ASD-STE100 Simplified Technical English (short common words, active voice, max 20-25 words per sentence, no filler) so AI agents read terse, unambiguous facts.
- **`obsidian-cli`**: Triggered when interacting with Obsidian vault notes, searching existing vault knowledge, or creating notes via CLI.
---
## 📝 Document Style Guidelines
### Gitea README (`README.md`)
- Tone: Direct, professional, developer-focused.
- Sections: Overview, Key Tools & Demonstrated Skills (Resume alignment), Quick Start / Setup, Architecture Diagram, API / Usage details.
- Length: Concise, clean, bullet-focused.
### Obsidian Note (`<NoteName>.md`)
- Tone: Human-friendly, conversational yet structured.
- Sections: What is this? (Plain English), Why it matters / Portfolio showcase, Key Tools & Concepts, Architecture Overview (Mermaid), Related Notes.
- Length: Brief and intuitive.
### Vikunja Tasks
- Tone: Imperative, high-level, human-actionable.
- Examples: `"Configure Caddy reverse proxy"`, `"Test API endpoints"`, `"Deploy v1.0 to production"`.
### Outline AI Context (`outline-ai-context.md`)
- Tone: Terse, plain, active voice. **Strictly enforces `ste-writing` skill rules**.
- Document Catalog: Itemizes all collection documents with 1-sentence scopes and file paths so AI agents inject only the exact document needed.
- Structure: Document Catalog (Index), System Purpose, Configuration & Ports, File Map, Agent Resume Runbook.
- Length: Very brief, highly concise, zero fluff.
---
## 🚀 Per-Project Activation & Workflow
To enable `project-docs` on any project workspace:
To enable on any project:
```bash
/config-add skill project-docs
/reload
```
To invoke:
- Initiate: *"Initiate project documentation using project-docs"*
- Update: *"Update project docs across Gitea, Obsidian, Vikunja, and Outline"*
---
## 🎯 Platform Roles & Output Matrix
When invoked, `project-docs` coordinates five documentation layers:
| Platform | Target Audience | Purpose & Tone | Generated / Updated Artifacts |
| :--- | :--- | :--- | :--- |
| **Gitea** | Developers / Resume | Technical documentation & repository README. **Standard concise markdown**. Highlights tech stack, usage, and key tools/skills demonstrated for employment. | `<project>/README.md` (embedded Mermaid diagram, Archify links, setup/usage guide). |
| **Obsidian** | Humans / Hiring Managers | **Human understanding**. Simple, clear, layperson-friendly language, brief. Highlights skills, tools, and concepts that showcase for employment while forming a usable tool for understanding things. | `<vault>/Projects/<ProjectName>.md` (simple overview, employment highlights, embedded Mermaid). |
| **Mermaid + Archify** | Architectural Visualization | High-level system architecture and interactive HTML maps. | 1. `<project>/docs/<topic>.mmd`<br>2. `<project>/docs/diagrams/<topic>.png` (rendered via `mmdc`)<br>3. `<project>/docs/<topic>-map.html` (rendered via Archify)<br>4. Published to `https://maps.lab.audasmedia.com.au/<project>/docs/`. |
| **Vikunja** | Humans | **High-level task tracking**. Simple, brief, actionable human steps (milestones, key deliverables). | Vikunja project board or `<project>/docs/vikunja-tasks.json`. |
| **Outline** | AI Agents | **Deep AI context & document index**. Itemizes what is in each document in the collection so AI agents can inject specific files directly without searching. **Strictly uses `ste-writing` skill rules** (Simplified Technical English). | `<project>/docs/outline/` collection (`00-index.md`, `01-system-overview.md`, `02-config-and-env.md`, `03-code-map.md`, `04-agent-runbook.md`). |
---
## 🔄 Modes of Operation
### Mode 1: Initiate (New Project Bootstrap)
Audits the current workspace and interactively prompts the user for each platform before generating clean initial docs from bundled templates.
### Mode 2: Update (Keep Docs in Sync)
Scans git commits, file edits, or structural changes, then updates affected documentation across Gitea, Obsidian, Mermaid/Archify, Vikunja, and Outline.
---
## 📋 Interactive Discovery & Confirmation Protocol
For every project, step through the 5 platforms and **ask/confirm** before writing:
1. **Gitea**: *"Does a Gitea repository exist for this project, or should it be created? [Repo Name]"*
2. **Obsidian**: *"Should an Obsidian project note be created for human understanding and portfolio showcase? [Confirm / Vault Location / Note Name]"*
3. **Mermaid & Archify**: *"Do you want a Mermaid architecture diagram and Archify interactive map for this project? [Confirm / Topic Name]"*
4. **Vikunja**: *"Should a Vikunja project/board be created for human task tracking? [Confirm / Board Name]"*
5. **Outline**: *"Should an Outline document collection be created for AI agents to resume context across restarts? [Confirm / Collection Name]"*
---
## 📐 Native Diagramming & Archify Execution Workflow
`project-docs` handles diagram generation and rendering natively using system tools:
### Step 1: Write Mermaid Source
Write source to `<project>/docs/<topic>.mmd`. Include click links to the published Archify map:
```mermaid
flowchart LR
U[User / Client] --> UI[Web Interface]
UI --> API[API Gateway]
API --> DB[(Database)]
click API "https://maps.lab.audasmedia.com.au/{{PROJECT_NAME}}/docs/" "View Archify Map"
click DB "https://maps.lab.audasmedia.com.au/{{PROJECT_NAME}}/docs/" "View Archify Map"
```
### Step 2: Render Image Files via mmdc
```bash
mkdir -p <project>/docs/diagrams
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --scale 2 -b white
```
### Step 3: Render Interactive Archify HTML Map
Use the bundled Archify engine (`~/.agents/skills/archify/`):
```bash
# 1. Author JSON IR at <project>/docs/archify/<topic>.architecture.json
# 2. Validate IR
node ~/.agents/skills/archify/bin/archify.mjs validate architecture <project>/docs/archify/<topic>.architecture.json --quality showcase --json
# 3. Deliver HTML Map
node ~/.agents/skills/archify/bin/archify.mjs deliver architecture <project>/docs/archify/<topic>.architecture.json <project>/docs/<topic>-map.html --quality showcase --json
```
### Step 4: Publish to LAN Maps Site
```bash
~/.agents/skills/project-docs/scripts/publish-maps.sh [<project-dir>]
```
Uploads `<project>/docs/` to `https://maps.lab.audasmedia.com.au/<project>/docs/`.
---
## ✍️ Outline & `ste-writing` Rules
Outline documentation **MUST** enforce ASD-STE100 Simplified Technical English (`ste-writing` rules):
1. **Terse & Concise**: Maximum 20-25 words per sentence. No filler words or AI slop ("utilize", "robust", "seamless", "ensure").
2. **Active Voice**: "The server reads the file" (not "The file is read by the server").
3. **Itemized Document Catalog**: The index document (`00-index.md`) MUST itemize every document in the collection with its file path and 1-sentence scope so AI agents can inject exact files without searching.
### Example Outline Document Catalog (`00-index.md`)
```markdown
# {{PROJECT_NAME}} — AI Document Index
> **Target**: AI Agents
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
## 📚 Document Catalog (Inject Specific Document)
Read this index to inject the exact file you need. Do not search all files.
| Document Title | Path | Scope / Description |
| :--- | :--- | :--- |
| **System Overview** | `docs/outline/01-system-overview.md` | Explains project purpose, main architecture, and active services. |
| **Configuration & Env** | `docs/outline/02-config-and-env.md` | Lists environment variables, config paths, network ports, and secrets. |
| **Code Structure Map** | `docs/outline/03-code-map.md` | Shows folder structure, core entry points, and primary dependencies. |
| **AI Agent Runbook** | `docs/outline/04-agent-runbook.md` | Gives step-by-step commands to build, test, and restart agent work. |
```
---
## 🛠 Script & Template References
Templates live in `~/.agents/skills/project-docs/templates/`:
- `templates/gitea-readme.md.tpl`
- `templates/obsidian-note.md.tpl`
- `templates/outline-ai-context.md.tpl`
- `templates/vikunja-tasks.json.tpl`
- `templates/mermaid-archify.mmd.tpl`
---
## 🚀 Activation & Usage Summary
```bash
# Enable in project
/config-add skill project-docs
/reload
# Initiate or Update
"Initiate documentation for this project"
"Update project documentation across Gitea, Obsidian, Vikunja, and Outline"
```