147 lines
7.2 KiB
Markdown
147 lines
7.2 KiB
Markdown
---
|
|
name: project-docs
|
|
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 (Unified Project Lifecycle & Documentation Master Skill)
|
|
|
|
`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.
|
|
|
|
To enable on any project:
|
|
```bash
|
|
/config-add skill project-docs
|
|
/reload
|
|
```
|
|
|
|
---
|
|
|
|
## 🎯 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"
|
|
```
|