Add project-docs lifecycle meta-skill

2026-09-15 14:42:57 +10:00
parent a34b41e215
commit 0312453035
6 changed files with 231 additions and 0 deletions
--- a/skills/project-docs/SKILL.md
+++ b/skills/project-docs/SKILL.md
@@ -0,0 +1,118 @@
+---
+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
+---
+
+# project-docs (Project Lifecycle & Documentation Meta-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`).
+
+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 & knowledge base**. Exhaustive configuration details, directions, architecture notes, and instructions for AI agents to pick up and resume context on future restarts. | Outline Document / Collection (deep context, env vars, agent runbook). |
+
+---
+
+## 🔄 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 & Resume Instructions)
+- **Check**: Does an Outline documentation page exist for AI resume?
+- **Ask/Confirm**: *"Should an Outline document be created for AI agents to resume context across restarts? [Confirm / Collection]"*
+- **Action**: Generate structured AI documentation containing architecture breakdown, environment variables, dependencies, and agent recovery steps.
+
+---
+
+## 🛠 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`.
+- **`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: Explicit, technical, context-dense, machine-oriented.
+- Sections: System Purpose, Stack & Environment Variables, File Map, Subagent Workflows, Known Quirks & Recovery Steps.
+- Length: Exhaustive technical detail for AI restarts.
+
+---
+
+## 🚀 Per-Project Activation & Workflow
+
+To enable `project-docs` on any project workspace:
+```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"*
--- a/skills/project-docs/templates/gitea-readme.md.tpl
+++ b/skills/project-docs/templates/gitea-readme.md.tpl
@@ -0,0 +1,25 @@
+# {{PROJECT_NAME}}
+
+{{PROJECT_SHORT_DESCRIPTION}}
+
+## 🛠 Demonstrated Skills & Tech Stack
+- **Core Technologies**: {{TECH_STACK}}
+- **Key Tools**: {{TOOLS_USED}}
+- **Engineering Capabilities**: {{DEMONSTRATED_SKILLS}}
+
+## 🚀 Quick Start
+
+```bash
+{{QUICK_START_COMMANDS}}
+```
+
+## 📐 System Architecture
+
+```mermaid
+{{MERMAID_DIAGRAM_SOURCE}}
+```
+
+*Interactive Architecture Map available at:* [maps.lab.audasmedia.com.au/{{PROJECT_NAME}}](https://maps.lab.audasmedia.com.au/{{PROJECT_NAME}}/)
+
+## 📝 Usage & Configuration
+{{USAGE_NOTES}}
--- a/skills/project-docs/templates/mermaid-archify.mmd.tpl
+++ b/skills/project-docs/templates/mermaid-archify.mmd.tpl
@@ -0,0 +1,8 @@
+flowchart LR
+    U[User / Client] --> UI[Web Interface / Client App]
+    UI --> API[API Gateway / Service Layer]
+    API --> DB[(Database / Storage)]
+    API --> AI[AI Agent Context / Engine]
+
+    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"
--- a/skills/project-docs/templates/obsidian-note.md.tpl
+++ b/skills/project-docs/templates/obsidian-note.md.tpl
@@ -0,0 +1,31 @@
+---
+tags:
+  - project
+  - {{PROJECT_TAG}}
+  - showcase
+skills:
+  - {{DEMONSTRATED_SKILLS_LIST}}
+tools:
+  - {{TOOLS_USED_LIST}}
+---
+
+# {{PROJECT_NAME}} — Overview
+
+## 💡 What is this project?
+{{HUMAN_EXPLANATION_SIMPLE}}
+
+## 🌟 Key Highlights (Portfolio & Employment)
+- **Concept**: {{KEY_CONCEPT}}
+- **Tools & Skills Showcase**: {{SHOWCASE_HIGHLIGHTS}}
+- **Practical Value**: {{PRACTICAL_VALUE}}
+
+## 📐 Architecture & Flow
+
+```mermaid
+{{MERMAID_DIAGRAM_SOURCE}}
+```
+
+## 🔗 Related Notes & Links
+- Gitea Repo: `{{GITEA_REPO_URL}}`
+- Interactive Map: [Archify Map](https://maps.lab.audasmedia.com.au/{{PROJECT_NAME}}/)
+- AI Context (Outline): `{{OUTLINE_DOC_URL}}`
--- a/skills/project-docs/templates/outline-ai-context.md.tpl
+++ b/skills/project-docs/templates/outline-ai-context.md.tpl
@@ -0,0 +1,27 @@
+# {{PROJECT_NAME}} — AI Agent Context & Context Recovery Guide
+
+> **Target Audience**: AI Coding Agents & LLMs  
+> **Purpose**: Deep context, environment variables, configuration directives, and restart runbooks for autonomous AI agents.
+
+## 🎯 System Overview & Intent
+{{SYSTEM_INTENT_DETAILED}}
+
+## ⚙️ Configuration & Environment
+- **Environment Variables**: {{ENV_VARIABLES}}
+- **Config Files**: {{CONFIG_PATHS}}
+- **Services & Ports**: {{SERVICES_AND_PORTS}}
+
+## 📁 Key File Map
+```
+{{DIRECTORY_TREE_SUMMARY}}
+```
+
+## 🔄 AI Agent Resume Protocol
+When restarting or resuming work on this project, an AI agent MUST:
+1. Verify system dependencies and services are running.
+2. Read `docs/outline-ai-context.md` (this file) for structural understanding.
+3. Check Git status and recent commits (`git log -n 5`).
+4. Execute validation tests: `{{VALIDATION_COMMANDS}}`.
+
+## ⚠️ Known Quirks & Recovery Runbooks
+{{KNOWN_QUIRKS_AND_RUNBOOKS}}
--- a/skills/project-docs/templates/vikunja-tasks.json.tpl
+++ b/skills/project-docs/templates/vikunja-tasks.json.tpl
@@ -0,0 +1,22 @@
+{
+  "title": "{{PROJECT_NAME}} - Human Task Overview",
+  "description": "High-level task checklist for human team members.",
+  "tasks": [
+    {
+      "title": "Confirm Gitea repository creation & standard README",
+      "done": false
+    },
+    {
+      "title": "Review Obsidian portfolio note and employment skill highlights",
+      "done": false
+    },
+    {
+      "title": "Verify Mermaid architecture diagram & Archify map link",
+      "done": false
+    },
+    {
+      "title": "Ensure Outline AI context doc is present for agent restarts",
+      "done": false
+    }
+  ]
+}