121 lines
7.6 KiB
Markdown
121 lines
7.6 KiB
Markdown
---
|
|
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 & 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:
|
|
```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"*
|