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

7.6 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 & 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:

/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