sam/pi-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
03124530354643861eaa02d5bcfd9b1c8f0d492a
pi-config/skills/project-docs/SKILL.md

7.0 KiB
Raw Blame History

name, description, version
name description version
project-docs 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. 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:

/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"
Reference in New Issue View Git Blame Copy Permalink