diff --git a/skills/project-docs/SKILL.md b/skills/project-docs/SKILL.md index 45d1ffa..eb53397 100644 --- a/skills/project-docs/SKILL.md +++ b/skills/project-docs/SKILL.md @@ -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. | `/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 & 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 `/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. --- diff --git a/skills/project-docs/templates/outline-ai-context.md.tpl b/skills/project-docs/templates/outline-ai-context.md.tpl index acb7f1e..38a3eb9 100644 --- a/skills/project-docs/templates/outline-ai-context.md.tpl +++ b/skills/project-docs/templates/outline-ai-context.md.tpl @@ -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}}`.