7.2 KiB
7.2 KiB
name, description, version
| name | description | version |
|---|---|---|
| project-docs | 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). | 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:
/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>.mmd2. <project>/docs/diagrams/<topic>.png (rendered via mmdc)3. <project>/docs/<topic>-map.html (rendered via Archify)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:
- Gitea: "Does a Gitea repository exist for this project, or should it be created? [Repo Name]"
- Obsidian: "Should an Obsidian project note be created for human understanding and portfolio showcase? [Confirm / Vault Location / Note Name]"
- Mermaid & Archify: "Do you want a Mermaid architecture diagram and Archify interactive map for this project? [Confirm / Topic Name]"
- Vikunja: "Should a Vikunja project/board be created for human task tracking? [Confirm / Board Name]"
- 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:
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
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/):
# 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
~/.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):
- Terse & Concise: Maximum 20-25 words per sentence. No filler words or AI slop ("utilize", "robust", "seamless", "ensure").
- Active Voice: "The server reads the file" (not "The file is read by the server").
- 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)
# {{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.tpltemplates/obsidian-note.md.tpltemplates/outline-ai-context.md.tpltemplates/vikunja-tasks.json.tpltemplates/mermaid-archify.mmd.tpl
🚀 Activation & Usage Summary
# 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"