Consolidate project documentation into single project-docs master skill
This commit is contained in:
@@ -1,104 +0,0 @@
|
||||
---
|
||||
name: project-diagramming-archify
|
||||
description: Create or update an interactive Archify architecture map for a project. Accept plain-language requirements or pasted Mermaid (flowchart/sequence/stateDiagram) and compile typed JSON IR into a self-contained interactive HTML diagram (architecture, workflow, sequence, dataflow, lifecycle) under the project's docs/ directory. Use when the user asks for architecture/flow/data visualization, or the diagrams were just created/updated with project-diagramming-mermaid. Per-project only — never global.
|
||||
version: 1.1.0
|
||||
---
|
||||
|
||||
# project-diagramming-archify
|
||||
|
||||
Create polished, validated, interactive architecture diagrams as standalone HTML (with inline SVG, dark/light themes, pan/zoom, search, route tracing, PNG/SVG/WebM export) from typed JSON IR, using the bundled `archify.mjs` renderer. Everything lands under the project's `docs/` directory.
|
||||
|
||||
## When to use
|
||||
|
||||
- User asks for a client-facing / interactive architecture or flow visualization.
|
||||
- The mermaid flow just completed (project-diagramming-mermaid) and the user said yes to the follow-up prompt.
|
||||
- User asks to update an existing Archify map.
|
||||
|
||||
## The skill asset
|
||||
|
||||
The renderer/vendor skill lives at `~/.agents/skills/archify/` (Archify v2.14, MIT, from tt-a1i/archify). It is self-contained: pure Node ≥18, zero npm deps. Key entry point:
|
||||
|
||||
```bash
|
||||
node ~/.agents/skills/archify/bin/archify.mjs <command> ...
|
||||
```
|
||||
|
||||
Commands (from the vendored skill's fast authoring path):
|
||||
- `guide "<scenario>" --json` — when unsure which diagram type fits the ask.
|
||||
- `validate <type> <candidate.json> --quality showcase --json` — iterate during authoring; **showcase pass = 9 artifact checks, 0 composition errors, 0 warnings**.
|
||||
- `validate <type> <candidate.json> --quality standard --json` — **dense-map tier**: 4 artifact checks, far fewer composition constraints. Use for rich/large topologies (see "Dense maps" below). Pass the same `--quality` to `deliver`.
|
||||
- `deliver <type> <candidate.json> <output.html> --quality showcase --json` — final acceptance (freezes spec bytes, atomically commits HTML, reports SHA-256 + byte counts).
|
||||
- `visual-check <output.html> --json` — best-effort screenshot/containment evidence; needs Chrome/Chromium, exit 2 = skipped gracefully (e.g. .13 has no chrome). Never claim visual inspection you did not perform.
|
||||
|
||||
## Canonical workflow (per project)
|
||||
|
||||
1. **Scope + type** — map the ask to a type: architecture (components/services/boundaries), workflow (processes/gates), sequence (API/request chains), dataflow (pipelines/ETL/lineage), lifecycle (state transitions). If ambiguous: `node ~/.agents/skills/archify/bin/archify.mjs guide "<scenario>" --json`.
|
||||
2. **Author JSON IR** — read one matching schema (`schemas/<type>.schema.json` + `schemas/common.schema.json`) and one matching example (`examples/<type>.*.json`) from the vendored skill. Author **fresh** JSON: new stable IDs, domain wording, layout. ≤ 12 primary nodes; one obvious main path; sparse labels. Set `meta.quality_profile` to `"showcase"` unless the user explicitly asks for a dense `standard` map.
|
||||
3. **Accept Mermaid input** (common path — after project-diagramming-mermaid): read the Mermaid for topology & meaning, then author fresh Archify JSON (do not mechanically copy styling):
|
||||
- `flowchart` / `graph` → `workflow`, or `architecture` for a component map.
|
||||
- `sequenceDiagram` → `sequence` (participants → semantic participants, arrows → messages).
|
||||
- `stateDiagram` → `lifecycle` (states & transitions keep meaning).
|
||||
4. **Validate-iterate**: `validate` after every candidate edit and immediately before handoff. Fix only diagnosed issues; if ~2–3 consecutive rounds don't improve the error count, stop iterating and use the **dense-map escape** below (standard profile / bigger viewBox / split) instead of forcing a simplified node set.
|
||||
5. **Deliver**: `deliver <type> <candidate.json> <output.html> --quality showcase --json`. Non-zero exit is never success.
|
||||
|
||||
## Dense maps — the sanctioned escape hatches (read before simplifying)
|
||||
|
||||
Archify is a **curation** tool, not an everything-map. Two hard gates can make a rich topology fight you:
|
||||
|
||||
- **showcase composition** — 9 checks: ≥8px segments, no edge-through-node, no ambiguous corridors, no label collisions.
|
||||
- **visual-check viewport fit** — the whole map must fit **1440×900 without scrolling** (`scrollWidth ≤ innerWidth && scrollHeight ≤ innerHeight` at every checked size). A 4-lane, 6-column flow physically cannot fit 900px tall → vertical overflow is expected for such maps.
|
||||
|
||||
When ~2–3 rounds don't improve, do **NOT** silently simplify to fewer nodes. Work through these in order, and tell the user what you did:
|
||||
|
||||
1. **Drop to `standard` quality** (recommended for dense maps) — pass `--quality standard` to BOTH `validate` and `deliver` (4 artifact checks instead of 9; the §composition constraints that blocked you are mostly gone). A user who asks for a rich/dense map IS asking for standard — the skill's default is showcase *unless the user explicitly requests a dense standard map*.
|
||||
2. **Enlarge `meta.viewBox`** — schema min is 320×240, **no max** (examples ship up to 1080×780). More Y room fixes squeezed lanes. Caveat: to still *pass* visual-check, keep total height ≤ ~900px; anything taller may overflow (report it truthfully — never fake a pass with `overflow: hidden`).
|
||||
3. **Split into multiple maps** — main flow in one map; detail (rejected paths, secondary stores) in a second map or as `cards` / Obsidian / Outline content. One obvious main path is the design philosophy; low-value edges belong in cards, not the canvas.
|
||||
4. **Only then** simplify the node set — and say so explicitly ("kept the N-node validated map; detail lives in X").
|
||||
|
||||
> Design envelope: shipped examples run **10–12 primary components**, viewBox 720×900 → 1080×780. Above ~12 primary nodes → split-map territory, not an everything-map.
|
||||
|
||||
## Output locations (per-project, always under the project's docs/)
|
||||
|
||||
- **JSON IR source (single source of truth):** `<project>/docs/archify/<topic>.<type>.json`
|
||||
- **Interactive HTML map:** `<project>/docs/<topic>-map.html`
|
||||
- Schemas/examples to consult: `~/.agents/skills/archify/schemas/`, `~/.agents/skills/archify/examples/`.
|
||||
|
||||
Create `<project>/docs/` (+ `docs/archify/`) if missing. Never write artifacts outside the project directory.
|
||||
|
||||
## Publish to the central maps site (optional but recommended)
|
||||
|
||||
After a successful `deliver`, offer to **publish** the project's `docs/` to the LAN maps site:
|
||||
|
||||
```bash
|
||||
~/.agents/skills/project-diagramming-archify/publish-maps.sh [<project-dir>]
|
||||
```
|
||||
|
||||
- Uploads `docs/` to Caddy on `.35` → **`https://maps.lab.audasmedia.com.au/<project>/docs/`** (site index at `https://maps.lab.audasmedia.com.au/` — Caddy `file_server browse`, no auth, read-only static hosting).
|
||||
- **Incremental + atomic** (rsync -az): only changed blocks transfer; no half-written files on failure.
|
||||
- Excludes `*.visual-check.*` sidecars automatically (keeps the browse index clean).
|
||||
- Works from any machine with ssh key access to `.35` (all three pi machines have it).
|
||||
- `publish-maps.sh --list` shows what's already published.
|
||||
- Wait for `visual-check` to pass first; `publish-maps.sh` does NOT re-run it.
|
||||
|
||||
## Authoring rules (subset of the vendored skill — read SKILL.md for full invariants)
|
||||
|
||||
- Omit `meta.visual_preset`, `meta.subtitle`, `meta.legend`, `meta.engineering_profile` by default.
|
||||
- Omit `meta.viewBox` by default (schema min 320×240, no max); **enlarge it for dense maps** so lanes/labels fit cleanly without shrinking nodes.
|
||||
- Match authored strings to the user's language; preserve exact product names / commands / API paths / env names.
|
||||
- Automatic routes own their endpoint sides; never accept an edge crossing an unrelated opaque node.
|
||||
- Sequence: omit `meta.column_fit` (fixed); use `"spread"` when participants don't fit.
|
||||
- Component types: `frontend`, `backend`, `database`, `cloud`, `security`, `messagebus`, `external`. Variants: `default`, `emphasis`, `security`, `dashed`.
|
||||
|
||||
## Per-project activation
|
||||
|
||||
Activated **per project** with `/config-add skill project-diagramming-archify` (and the vendor skill `archify` is the renderer asset). If not available in the current project, that's expected — assets activate per project to keep context lean.
|
||||
|
||||
## Related
|
||||
|
||||
- `project-diagramming-mermaid` — Mermaid flow that feeds into this skill (and the user-facing prompt to come here).
|
||||
- `pi-mermaid` extension — ASCII preview of Mermaid in-chat.
|
||||
- `nixos-workflow` skill — asset management (Gitea pi-config).
|
||||
- `system-architect` skill — infra reference.
|
||||
|
||||
## Obsidian documentation
|
||||
|
||||
Tools documented at `300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md` (+ the network & container docs link it). Do not recreate diagram versions of those docs.
|
||||
@@ -1,96 +0,0 @@
|
||||
---
|
||||
name: project-diagramming-mermaid
|
||||
description: Use Mermaid to create or update a project diagram. Outline a codebase, project, or system using Mermaid syntax inside standard Markdown fenced blocks, then render it to PNG/SVG (and keep the Mermaid source) under the project's docs/ directory. Use when the user asks to map, outline, diagram, or visualize a codebase/project/system, or to update an existing project diagram. After producing the Mermaid diagram, prompt the user to also create or update the Archify doc. Per-project only — never global.
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# project-diagramming-mermaid
|
||||
|
||||
Diagram a codebase or project with Mermaid, render to image files, all under the project's `docs/` directory.
|
||||
|
||||
## When to use
|
||||
|
||||
- User asks to outline/map/visualize a codebase, project, system, or data flow at a high level.
|
||||
- User asks to update an existing Mermaid project diagram.
|
||||
- User asks to document the home network, Docker containers, or any infra — but see the Obsidian note below.
|
||||
|
||||
## Workflow (overview)
|
||||
|
||||
1. **Scope** — clarify target: whole project, a subsystem, or a specific flow. Focus on high-level dependencies and data flows. Avoid complex layout overlaps (prefer `<project>/docs/` artifacts that are readable, not exhaustive).
|
||||
2. **Author Mermaid source** — write the diagram as a fenced ` ```mermaid ` block in the appropriate Markdown doc. See "Where the source lives" below.
|
||||
3. **Save source** — write the Mermaid source to `<project>/docs/<topic>.mmd`.
|
||||
4. **Render** — render to `<project>/docs/diagrams/<topic>.png` (and optionally `.svg`) via `mmdc`.
|
||||
5. **Prompt Archify** — after the Mermaid diagram is done, ask the user: "Create/update the Archify doc for this too?" (see `project-diagramming-archify` skill). Do this automatically, not just when asked.
|
||||
|
||||
## Where the source lives
|
||||
|
||||
Artifacts for a project go **under that project's `docs/`** — everything is per-project in this setup:
|
||||
|
||||
- **Source (single source of truth):** `<project>/docs/<topic>.mmd`
|
||||
- **Markdown doc with the fenced block:** the project's main doc(s), e.g. `<project>/docs/README.md`, `<project>/docs/<topic>.md`, `<project>/README.md` — anywhere the user wants the diagram visible (Obsidian renders ` ```mermaid ` natively).
|
||||
- **Rendered images:** `<project>/docs/diagrams/<topic>.png` (+ `.svg` when requested)
|
||||
|
||||
If `<project>/docs/` does not exist, create it. Never write diagram artifacts outside the project directory.
|
||||
|
||||
## Writing good Mermaid
|
||||
|
||||
High-level, readable diagrams — not layout spaghetti:
|
||||
|
||||
- **Flowchart** (`graph TD` / `flowchart LR`) for dependencies and data flows. Use `A --> B` for dependency/data flow, `A -.-> B` for optional, subgraphs for grouping.
|
||||
- **Sequence** (`sequenceDiagram`) for request/API flows with participants.
|
||||
- **Class** (rare) for type structure; **ER** (`erDiagram`) for data model; **stateDiagram-v2** for lifecycle.
|
||||
- Keep node labels short. Add them with `A[Label text]`. Edge labels `A -->|"verb"| B`.
|
||||
- Avoid deeply nested subgraphs and crossing edges — if it gets busy, split into multiple diagrams per topic.
|
||||
- Prefer `flowchart LR` for wide dependency chains (reads better on screens), `graph TD` for hierarchies.
|
||||
|
||||
Example:
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U[User] --> W[Web UI] --> API[API Gateway] --> DB[(Postgres)]
|
||||
API --> Q[Message Queue] --> W1[Worker] --> DB
|
||||
```
|
||||
|
||||
## Rendering with mmdc (mermaid-cli)
|
||||
|
||||
- `mmdc` is provided by **nixpkgs `mermaid-cli`** (`pkgs.mermaid-cli`, v11.16.0) installed in `home.packages` on .27 / .13 / .51. It bundles its own Chromium from the Nix store — deterministic, offline, private. See system-architect skill for machine details.
|
||||
- Check availability: `which mmdc`. If missing, it's a Nix install (home.nix `home.packages`) — NOT an npm install (Nix store is read-only). Tell the user.
|
||||
|
||||
Commands:
|
||||
|
||||
```bash
|
||||
# PNG (default 4x for crispness with --scale; choose scale for size)
|
||||
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --scale 2 -b white
|
||||
|
||||
# SVG (vector, good for docs)
|
||||
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.svg
|
||||
|
||||
# Use a theme/style: -t dark|neutral|forest|base
|
||||
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --theme neutral
|
||||
```
|
||||
|
||||
After rendering, verify the file exists and is non-trivial in size (a few KB+). If mmdc fails, read the error — most failures are syntax errors in the diagram; fix and re-run.
|
||||
|
||||
## Prompt the user for the Archify follow-up
|
||||
|
||||
After a successful Mermaid diagram, always ask (or offer via the flow below):
|
||||
|
||||
> "Diagram saved to `<project>/docs/diagrams/<topic>.png`. Create/update the Archify doc too?"
|
||||
|
||||
If yes (or user asked originally), invoke the **project-diagramming-archify** skill — Archify accepts Mermaid (flowchart → workflow/architecture, sequence → sequence, stateDiagram → lifecycle) directly, so the handoff is cheap.
|
||||
|
||||
## Per-project activation
|
||||
|
||||
This skill is activated **per project** with `/config-add skill project-diagramming-mermaid` (never globally — reduces context bloat). If it's not available in the current project, that's expected; assets activate per project via the pi-config extension.
|
||||
|
||||
## Related
|
||||
|
||||
- `project-diagramming-archify` — interactive HTML architecture maps (the client-facing output).
|
||||
- `pi-mermaid` extension — renders ` ```mermaid ` blocks as ASCII in the TUI for quick in-chat preview + parser warnings/errors.
|
||||
- `nixos-workflow` skill — how Pi assets are managed (Gitea `pi-config`, per-machine clones).
|
||||
- `system-architect` skill — machine/infra reference for .27/.13/.51 etc.
|
||||
|
||||
## Obsidian documentation (context, if asked)
|
||||
|
||||
These tools (Mermaid, Archify, Vikunja, Outline) are documented as tools in Obsidian:
|
||||
`300 areas/360 Dev-Ops Network Computers/Dev-Ops Tooling — Mermaid, Archify, Vikunja & Outline.md`, plus `Home Network Map Overview.md` and `Docker Containers.md` link to it. Do not recreate diagram versions of the network/container docs.
|
||||
@@ -1,120 +1,146 @@
|
||||
---
|
||||
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
|
||||
description: The single self-contained master skill for initiating or updating all project documentation across Gitea, Obsidian, Mermaid/Archify, Vikunja, and Outline. Handles technical READMEs, human portfolio notes, architecture diagrams & Archify maps, task tracking, and AI context catalogs using Simplified Technical English (ste-writing).
|
||||
version: 2.0.0
|
||||
---
|
||||
|
||||
# project-docs (Project Lifecycle & Documentation Meta-Skill)
|
||||
# project-docs (Unified Project Lifecycle & Documentation Master 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`).
|
||||
`project-docs` is the **single entry point** for all project documentation across your stack. You do not need to load separate diagramming or documentation skills — `project-docs` handles everything natively.
|
||||
|
||||
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:
|
||||
To enable on any project:
|
||||
```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"*
|
||||
---
|
||||
|
||||
## 🎯 Platform Roles & Output Matrix
|
||||
|
||||
When invoked, `project-docs` coordinates five documentation layers:
|
||||
|
||||
| Platform | Target Audience | Purpose & Tone | Generated / Updated Artifacts |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **Gitea** | Developers / Resume | Technical documentation & repository README. **Standard concise markdown**. Highlights tech stack, usage, and key tools/skills demonstrated for employment. | `<project>/README.md` (embedded Mermaid diagram, Archify links, setup/usage guide). |
|
||||
| **Obsidian** | Humans / Hiring Managers | **Human understanding**. Simple, clear, layperson-friendly language, brief. Highlights skills, tools, and concepts 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 interactive HTML maps. | 1. `<project>/docs/<topic>.mmd`<br>2. `<project>/docs/diagrams/<topic>.png` (rendered via `mmdc`)<br>3. `<project>/docs/<topic>-map.html` (rendered via Archify)<br>4. Published to `https://maps.lab.audasmedia.com.au/<project>/docs/`. |
|
||||
| **Vikunja** | Humans | **High-level task tracking**. Simple, brief, actionable human steps (milestones, key deliverables). | Vikunja project board or `<project>/docs/vikunja-tasks.json`. |
|
||||
| **Outline** | AI Agents | **Deep AI context & document index**. Itemizes what is in each document in the collection so AI agents can inject specific files directly without searching. **Strictly uses `ste-writing` skill rules** (Simplified Technical English). | `<project>/docs/outline/` collection (`00-index.md`, `01-system-overview.md`, `02-config-and-env.md`, `03-code-map.md`, `04-agent-runbook.md`). |
|
||||
|
||||
---
|
||||
|
||||
## 🔄 Modes of Operation
|
||||
|
||||
### Mode 1: Initiate (New Project Bootstrap)
|
||||
Audits the current workspace and interactively prompts the user for each platform before generating clean initial docs from bundled templates.
|
||||
|
||||
### Mode 2: Update (Keep Docs in Sync)
|
||||
Scans git commits, file edits, or structural changes, then updates affected documentation across Gitea, Obsidian, Mermaid/Archify, Vikunja, and Outline.
|
||||
|
||||
---
|
||||
|
||||
## 📋 Interactive Discovery & Confirmation Protocol
|
||||
|
||||
For every project, step through the 5 platforms and **ask/confirm** before writing:
|
||||
|
||||
1. **Gitea**: *"Does a Gitea repository exist for this project, or should it be created? [Repo Name]"*
|
||||
2. **Obsidian**: *"Should an Obsidian project note be created for human understanding and portfolio showcase? [Confirm / Vault Location / Note Name]"*
|
||||
3. **Mermaid & Archify**: *"Do you want a Mermaid architecture diagram and Archify interactive map for this project? [Confirm / Topic Name]"*
|
||||
4. **Vikunja**: *"Should a Vikunja project/board be created for human task tracking? [Confirm / Board Name]"*
|
||||
5. **Outline**: *"Should an Outline document collection be created for AI agents to resume context across restarts? [Confirm / Collection Name]"*
|
||||
|
||||
---
|
||||
|
||||
## 📐 Native Diagramming & Archify Execution Workflow
|
||||
|
||||
`project-docs` handles diagram generation and rendering natively using system tools:
|
||||
|
||||
### Step 1: Write Mermaid Source
|
||||
Write source to `<project>/docs/<topic>.mmd`. Include click links to the published Archify map:
|
||||
```mermaid
|
||||
flowchart LR
|
||||
U[User / Client] --> UI[Web Interface]
|
||||
UI --> API[API Gateway]
|
||||
API --> DB[(Database)]
|
||||
|
||||
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"
|
||||
```
|
||||
|
||||
### Step 2: Render Image Files via mmdc
|
||||
```bash
|
||||
mkdir -p <project>/docs/diagrams
|
||||
mmdc -i <project>/docs/<topic>.mmd -o <project>/docs/diagrams/<topic>.png --scale 2 -b white
|
||||
```
|
||||
|
||||
### Step 3: Render Interactive Archify HTML Map
|
||||
Use the bundled Archify engine (`~/.agents/skills/archify/`):
|
||||
```bash
|
||||
# 1. Author JSON IR at <project>/docs/archify/<topic>.architecture.json
|
||||
# 2. Validate IR
|
||||
node ~/.agents/skills/archify/bin/archify.mjs validate architecture <project>/docs/archify/<topic>.architecture.json --quality showcase --json
|
||||
|
||||
# 3. Deliver HTML Map
|
||||
node ~/.agents/skills/archify/bin/archify.mjs deliver architecture <project>/docs/archify/<topic>.architecture.json <project>/docs/<topic>-map.html --quality showcase --json
|
||||
```
|
||||
|
||||
### Step 4: Publish to LAN Maps Site
|
||||
```bash
|
||||
~/.agents/skills/project-docs/scripts/publish-maps.sh [<project-dir>]
|
||||
```
|
||||
Uploads `<project>/docs/` to `https://maps.lab.audasmedia.com.au/<project>/docs/`.
|
||||
|
||||
---
|
||||
|
||||
## ✍️ Outline & `ste-writing` Rules
|
||||
|
||||
Outline documentation **MUST** enforce ASD-STE100 Simplified Technical English (`ste-writing` rules):
|
||||
|
||||
1. **Terse & Concise**: Maximum 20-25 words per sentence. No filler words or AI slop ("utilize", "robust", "seamless", "ensure").
|
||||
2. **Active Voice**: "The server reads the file" (not "The file is read by the server").
|
||||
3. **Itemized Document Catalog**: The index document (`00-index.md`) MUST itemize every document in the collection with its file path and 1-sentence scope so AI agents can inject exact files without searching.
|
||||
|
||||
### Example Outline Document Catalog (`00-index.md`)
|
||||
|
||||
```markdown
|
||||
# {{PROJECT_NAME}} — AI Document Index
|
||||
|
||||
> **Target**: AI Agents
|
||||
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`).
|
||||
|
||||
## 📚 Document Catalog (Inject Specific Document)
|
||||
Read this index to inject the exact file you need. Do not search all files.
|
||||
|
||||
| Document Title | Path | Scope / Description |
|
||||
| :--- | :--- | :--- |
|
||||
| **System Overview** | `docs/outline/01-system-overview.md` | Explains project purpose, main architecture, and active services. |
|
||||
| **Configuration & Env** | `docs/outline/02-config-and-env.md` | Lists environment variables, config paths, network ports, and secrets. |
|
||||
| **Code Structure Map** | `docs/outline/03-code-map.md` | Shows folder structure, core entry points, and primary dependencies. |
|
||||
| **AI Agent Runbook** | `docs/outline/04-agent-runbook.md` | Gives step-by-step commands to build, test, and restart agent work. |
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🛠 Script & Template References
|
||||
|
||||
Templates live in `~/.agents/skills/project-docs/templates/`:
|
||||
- `templates/gitea-readme.md.tpl`
|
||||
- `templates/obsidian-note.md.tpl`
|
||||
- `templates/outline-ai-context.md.tpl`
|
||||
- `templates/vikunja-tasks.json.tpl`
|
||||
- `templates/mermaid-archify.mmd.tpl`
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Activation & Usage Summary
|
||||
|
||||
```bash
|
||||
# Enable in project
|
||||
/config-add skill project-docs
|
||||
/reload
|
||||
|
||||
# Initiate or Update
|
||||
"Initiate documentation for this project"
|
||||
"Update project documentation across Gitea, Obsidian, Vikunja, and Outline"
|
||||
```
|
||||
|
||||
@@ -48,4 +48,4 @@ rsync -az \
|
||||
"$DOCS/" "$REMOTE:$DEST/"
|
||||
|
||||
echo "✓ published: https://maps.lab.audasmedia.com.au/$NAME/docs/"
|
||||
echo " (site index: https://maps.lab.audasmedia.com.au/)"
|
||||
echo " (site index: https://maps.lab.audasmedia.com.au/)"
|
||||
@@ -1,95 +0,0 @@
|
||||
---
|
||||
name: project-ops
|
||||
description: Access project tasks, stages and progress via Vikunja, and project documentation via Outline. Use for reading/creating/updating tasks, moving tasks between buckets (kanban stages), tracking percent done, and reading/writing docs on the home lab.
|
||||
compatibility: all pi-agents (sam-4screen-desktop .27, nixos-desktop .13, ubuntu1 .35, machine .51)
|
||||
---
|
||||
|
||||
# Project Ops — Vikunja (tasks/stages/progress) + Outline (documentation)
|
||||
|
||||
> The home-lab's project layer for any pi agent. **Vikunja** = tasks, kanban stages/buckets,
|
||||
> percent-done progress. **Outline** = project documentation.
|
||||
> These are shared across all four machines; keys are in the environment secrets.
|
||||
|
||||
## 1. Secrets (bearer tokens)
|
||||
|
||||
Keys are stored in the machine's secrets file. Read them at runtime, never print them:
|
||||
|
||||
- **Vikunja** token: `VIKUNJA_TOKEN` in `~/.config/environment.d/10-secrets.conf`
|
||||
- **Outline** key: `OL_API_KEY` in `~/.config/environment.d/10-secrets.conf`
|
||||
|
||||
```bash
|
||||
VIKUNJA_TOKEN=$(grep "^VIKUNJA_TOKEN=" ~/.config/environment.d/10-secrets.conf | head -1 | cut -d= -f2- | tr -d '"' | tr -d ' ')
|
||||
OL_API_KEY=$(grep "^OL_API_KEY=" ~/.config/environment.d/10-secrets.conf | head -1 | cut -d= -f2- | tr -d '"' | tr -d ' ')
|
||||
```
|
||||
|
||||
If token 401s: **Vikunja sometimes intermittently rejects a valid token** (transient; observed on LAN). First **retry once** — the same call returning 401 then 200 with an identical token is a known flake, not a wrong value. Only if a retry still 401s: re-source the secrets (new shell/login) so the fresh value is read; if still failing, ask the user to confirm the token was regenerated in Vikunja and re-placed. Outline keys are stable (401 there = genuinely wrong key).
|
||||
Never commit or echo the token values.
|
||||
|
||||
## 2. Vikunja API (tasks, stages, progress)
|
||||
|
||||
Base: `https://vikunja.lab.audasmedia.com.au/api/v1`
|
||||
Auth header: `Authorization: Bearer $VIKUNJA_TOKEN` (plus `Content-Type: application/json` on writes).
|
||||
|
||||
### Read
|
||||
```bash
|
||||
# all projects
|
||||
curl -s "$BASE/projects?page=1&per_page=100" -H "Authorization: Bearer $VIKUNJA_TOKEN"
|
||||
|
||||
# tasks in a project (project_id from above)
|
||||
curl -s "$BASE/projects/<project_id>/tasks?page=1&per_page=100" -H "Authorization: Bearer $VIKUNJA_TOKEN"
|
||||
|
||||
# a single task (shows bucket_id, percent_done, due_date)
|
||||
curl -s "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN"
|
||||
```
|
||||
|
||||
### Create a task
|
||||
```bash
|
||||
curl -s -X PUT "$BASE/projects/<project_id>/tasks" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"title":"new task","project_id":<project_id>}'
|
||||
```
|
||||
|
||||
### Update task — stage / progress / done
|
||||
```bash
|
||||
# move task to a kanban bucket ("stage"). Find bucket ids first:
|
||||
curl -s "$BASE/projects/<project_id>/buckets" -H "Authorization: Bearer $VIKUNJA_TOKEN"
|
||||
# then update the task; POST /tasks/<id> with any of: bucket_id, percent_done, done, due_date, priority
|
||||
curl -s -X POST "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"bucket_id":<bucket_id>,"percent_done":50}'
|
||||
# mark done
|
||||
curl -s -X POST "$BASE/tasks/<task_id>" -H "Authorization: Bearer $VIKUNJA_TOKEN" \
|
||||
-H "Content-Type: application/json" -d '{"done":true}'
|
||||
```
|
||||
|
||||
## 3. Outline API (documentation)
|
||||
|
||||
Base: `https://outline.lab.audasmedia.com.au/api`
|
||||
Same bearer pattern (`Authorization: Bearer $OL_API_KEY`, `Content-Type: application/json`). Endpoints are **POST**.
|
||||
|
||||
> ⚠️ **Known flakiness:** the public (Caddy) endpoint intermittently returns **502** on writes/reads. If you get a 502, **retry once** (often transient). For reliable create/update (e.g. `documents.create`), go **directly to the container**: `POST http://127.0.0.1:3000/api/...` from `.13` (same key).
|
||||
|
||||
```bash
|
||||
# collections (top-level doc groups)
|
||||
curl -s -X POST "$OL_BASE/collections.list" -H "Authorization: Bearer $OL_API_KEY" \
|
||||
-H "Content-Type: application/json" -d '{"limit":50}'
|
||||
|
||||
# documents in a collection
|
||||
curl -s -X POST "$OL_BASE/documents.list" -H "Authorization: Bearer $OL_API_KEY" \
|
||||
-H "Content-Type: application/json" -d '{"collectionId":"<id>","limit":50}'
|
||||
|
||||
# search docs
|
||||
curl -s -X POST "$OL_BASE/documents.search" -H "Authorization: Bearer $OL_API_KEY" \
|
||||
-H "Content-Type: application/json" -d '{"query":"<search terms>","limit":10}'
|
||||
|
||||
# reliable direct create (on .13):
|
||||
curl -s -X POST "http://127.0.0.1:3000/api/documents.create" -H "Authorization: Bearer $OL_API_KEY" \
|
||||
-H "Content-Type: application/json" -d '{"collectionId":"<id>","title":"<T>","text":"<md>","publish":true}'
|
||||
```
|
||||
|
||||
## 4. Guidance
|
||||
|
||||
- When a user asks about a project's tasks/progress: use Vikunja. When they want the "what/why/how" documentation: use Outline.
|
||||
- Keep payloads minimal; fetch then update (don't guess ids). Always confirm the write succeeded and report the outcome concisely (task moved to stage X / created id Y / doc found Z).
|
||||
- This skill has full scope (create/update/move/delete + docs read/write unless stated otherwise).
|
||||
- Works on all lab machines; records are shared, so changes appear everywhere.
|
||||
Reference in New Issue
Block a user