Update project-docs skill with Outline document catalog index & ste-writing integration
This commit is contained in:
@@ -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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,27 +1,30 @@
|
||||
# {{PROJECT_NAME}} — AI Agent Context & Context Recovery Guide
|
||||
# {{PROJECT_NAME}} — AI Document Index & Context
|
||||
|
||||
> **Target Audience**: AI Coding Agents & LLMs
|
||||
> **Purpose**: Deep context, environment variables, configuration directives, and restart runbooks for autonomous AI agents.
|
||||
> **Target**: AI Agents
|
||||
> **Writing Style**: ASD-STE100 Simplified Technical English (`ste-writing`). Brief, terse, active voice.
|
||||
|
||||
## 🎯 System Overview & Intent
|
||||
{{SYSTEM_INTENT_DETAILED}}
|
||||
## 📚 Document Catalog (Inject Specific Document)
|
||||
Read this index to inject the exact file you need. Do not search all files.
|
||||
|
||||
## ⚙️ Configuration & Environment
|
||||
- **Environment Variables**: {{ENV_VARIABLES}}
|
||||
- **Config Files**: {{CONFIG_PATHS}}
|
||||
- **Services & Ports**: {{SERVICES_AND_PORTS}}
|
||||
| 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. |
|
||||
|
||||
## 📁 Key File Map
|
||||
```
|
||||
{{DIRECTORY_TREE_SUMMARY}}
|
||||
```
|
||||
---
|
||||
|
||||
## 🔄 AI Agent Resume Protocol
|
||||
When restarting or resuming work on this project, an AI agent MUST:
|
||||
1. Verify system dependencies and services are running.
|
||||
2. Read `docs/outline-ai-context.md` (this file) for structural understanding.
|
||||
3. Check Git status and recent commits (`git log -n 5`).
|
||||
4. Execute validation tests: `{{VALIDATION_COMMANDS}}`.
|
||||
## 🎯 System Summary
|
||||
{{SYSTEM_INTENT_STE_TERSE}}
|
||||
|
||||
## ⚠️ Known Quirks & Recovery Runbooks
|
||||
{{KNOWN_QUIRKS_AND_RUNBOOKS}}
|
||||
## ⚙️ Core Configuration
|
||||
- **Env File**: `{{ENV_FILE_PATH}}`
|
||||
- **Config Directory**: `{{CONFIG_DIR_PATH}}`
|
||||
- **Active Ports**: `{{ACTIVE_PORTS}}`
|
||||
|
||||
## 🔄 Agent Restart Steps
|
||||
1. Read the Document Catalog above. Inject only required files.
|
||||
2. Check git status: `git status`.
|
||||
3. Check recent commits: `git log -n 5 --oneline`.
|
||||
4. Run validation test: `{{VALIDATION_COMMAND}}`.
|
||||
|
||||
Reference in New Issue
Block a user