sam/pi-config
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Update project-docs skill with Outline document catalog index & ste-writing integration

Browse Source
This commit is contained in:
Sam Rolfe
2026-09-16 05:43:20 +10:00
parent 0312453035
commit f968c928c5
2 changed files with 34 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
skills/project-docs/SKILL.md
View File

@@ -22,7 +22,7 @@ Each platform serves a specific role, audience, tone, and scope:
| **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). |
| **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). |
---
@@ -66,10 +66,10 @@ Before creating or altering any documentation asset, `project-docs` MUST **ask a
- **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.
### 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.
---
@@ -78,6 +78,7 @@ Before creating or altering any documentation asset, `project-docs` MUST **ask a
- **`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.
---
@@ -99,9 +100,10 @@ Before creating or altering any documentation asset, `project-docs` MUST **ask a
- 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.
- 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.
---