--- 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. | `/Projects/.md` (simple overview, employment highlights, embedded Mermaid). | | **Mermaid + Archify** | Architectural Visualization | High-level system architecture and flow diagrams. | `/docs/.mmd`, embedded SVG/PNG in Gitea & Obsidian. Nodes link to `https://maps.lab.audasmedia.com.au//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 `/docs/.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 `/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 (`.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: ```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"*