diff --git a/skills/project-diagramming-archify/SKILL.md b/skills/project-diagramming-archify/SKILL.md deleted file mode 100644 index 7f1e13d..0000000 --- a/skills/project-diagramming-archify/SKILL.md +++ /dev/null @@ -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 ... -``` - -Commands (from the vendored skill's fast authoring path): -- `guide "" --json` — when unsure which diagram type fits the ask. -- `validate --quality showcase --json` — iterate during authoring; **showcase pass = 9 artifact checks, 0 composition errors, 0 warnings**. -- `validate --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 --quality showcase --json` — final acceptance (freezes spec bytes, atomically commits HTML, reports SHA-256 + byte counts). -- `visual-check --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 "" --json`. -2. **Author JSON IR** — read one matching schema (`schemas/.schema.json` + `schemas/common.schema.json`) and one matching example (`examples/.*.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 --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):** `/docs/archify/..json` -- **Interactive HTML map:** `/docs/-map.html` -- Schemas/examples to consult: `~/.agents/skills/archify/schemas/`, `~/.agents/skills/archify/examples/`. - -Create `/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 [] -``` - -- Uploads `docs/` to Caddy on `.35` → **`https://maps.lab.audasmedia.com.au//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. \ No newline at end of file diff --git a/skills/project-diagramming-mermaid/SKILL.md b/skills/project-diagramming-mermaid/SKILL.md deleted file mode 100644 index ccb193b..0000000 --- a/skills/project-diagramming-mermaid/SKILL.md +++ /dev/null @@ -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 `/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 `/docs/.mmd`. -4. **Render** — render to `/docs/diagrams/.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):** `/docs/.mmd` -- **Markdown doc with the fenced block:** the project's main doc(s), e.g. `/docs/README.md`, `/docs/.md`, `/README.md` — anywhere the user wants the diagram visible (Obsidian renders ` ```mermaid ` natively). -- **Rendered images:** `/docs/diagrams/.png` (+ `.svg` when requested) - -If `/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 /docs/.mmd -o /docs/diagrams/.png --scale 2 -b white - -# SVG (vector, good for docs) -mmdc -i /docs/.mmd -o /docs/diagrams/.svg - -# Use a theme/style: -t dark|neutral|forest|base -mmdc -i /docs/.mmd -o /docs/diagrams/.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 `/docs/diagrams/.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. \ No newline at end of file diff --git a/skills/project-docs/SKILL.md b/skills/project-docs/SKILL.md index eb53397..701d742 100644 --- a/skills/project-docs/SKILL.md +++ b/skills/project-docs/SKILL.md @@ -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. | `/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: +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. | `/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. | `/Projects/.md` (simple overview, employment highlights, embedded Mermaid). | +| **Mermaid + Archify** | Architectural Visualization | High-level system architecture and interactive HTML maps. | 1. `/docs/.mmd`
2. `/docs/diagrams/.png` (rendered via `mmdc`)
3. `/docs/-map.html` (rendered via Archify)
4. Published to `https://maps.lab.audasmedia.com.au//docs/`. | +| **Vikunja** | Humans | **High-level task tracking**. Simple, brief, actionable human steps (milestones, key deliverables). | Vikunja project board or `/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). | `/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 `/docs/.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 /docs/diagrams +mmdc -i /docs/.mmd -o /docs/diagrams/.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 /docs/archify/.architecture.json +# 2. Validate IR +node ~/.agents/skills/archify/bin/archify.mjs validate architecture /docs/archify/.architecture.json --quality showcase --json + +# 3. Deliver HTML Map +node ~/.agents/skills/archify/bin/archify.mjs deliver architecture /docs/archify/.architecture.json /docs/-map.html --quality showcase --json +``` + +### Step 4: Publish to LAN Maps Site +```bash +~/.agents/skills/project-docs/scripts/publish-maps.sh [] +``` +Uploads `/docs/` to `https://maps.lab.audasmedia.com.au//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" +``` diff --git a/skills/project-diagramming-archify/publish-maps.sh b/skills/project-docs/scripts/publish-maps.sh similarity index 96% rename from skills/project-diagramming-archify/publish-maps.sh rename to skills/project-docs/scripts/publish-maps.sh index 5058460..3f471f7 100755 --- a/skills/project-diagramming-archify/publish-maps.sh +++ b/skills/project-docs/scripts/publish-maps.sh @@ -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/)" \ No newline at end of file +echo " (site index: https://maps.lab.audasmedia.com.au/)" diff --git a/skills/project-ops/SKILL.md b/skills/project-ops/SKILL.md deleted file mode 100644 index ccdee63..0000000 --- a/skills/project-ops/SKILL.md +++ /dev/null @@ -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//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/" -H "Authorization: Bearer $VIKUNJA_TOKEN" -``` - -### Create a task -```bash -curl -s -X PUT "$BASE/projects//tasks" -H "Authorization: Bearer $VIKUNJA_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"title":"new task","project_id":}' -``` - -### Update task — stage / progress / done -```bash -# move task to a kanban bucket ("stage"). Find bucket ids first: -curl -s "$BASE/projects//buckets" -H "Authorization: Bearer $VIKUNJA_TOKEN" -# then update the task; POST /tasks/ with any of: bucket_id, percent_done, done, due_date, priority -curl -s -X POST "$BASE/tasks/" -H "Authorization: Bearer $VIKUNJA_TOKEN" \ - -H "Content-Type: application/json" \ - -d '{"bucket_id":,"percent_done":50}' -# mark done -curl -s -X POST "$BASE/tasks/" -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":"","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":"","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":"","title":"","text":"","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. \ No newline at end of file