@trespies-source/dojo-genesis-plugin 1.0.0

package/skills/status-template/SKILL.md

@@ -0,0 +1,211 @@
+---
+name: status-template
+description: Write comprehensive status documents for software projects using a 10-section template bridging heartbeat, anatomy, and checkup perspectives. Use when writing status reports, creating project overviews, documenting codebase state, preparing handoffs, or auditing project health. Trigger phrases: 'write a status report', 'give me the lay of the land', 'where are we right now', 'create a project overview', 'document the current state', 'prepare a handoff document'.
+---
+
+> **OpenClaw Integration:** This skill is invoked by the Dojo Genesis plugin via `/dojo run status-template`.
+> The agent receives project context automatically via the `before_agent_start` hook.
+> Use `dojo_get_context` for full state, `dojo_save_artifact` to persist outputs,
+> and `dojo_update_state` to record phase transitions and decisions.
+
+# Status Template Skill
+
+**Version:** 1.0
+**Created:** 2026-02-08
+**Author:** Cruz + Manus (Cowork)
+**Origin:** Elevated from the `repo-status` skill's status template reference, which was itself codified from a live status-writing + file-management + health-audit session.
+**Lineage:** status-writing (heartbeat) + file-management (anatomy) + health-audit (checkup) → repo-status → this standalone skill.
+
+---
+
+## I. The Philosophy: One Document, Three Perspectives
+
+Project status lives in too many places — Slack threads, standup notes, README footers, someone's head. When a new person (or agent) arrives and asks "where are we?", the answer is usually scattered, stale, or both.
+
+This skill produces a single `.status.md` file that answers that question by looking at the project from three angles:
+
+- **Heartbeat (status-writing):** Is it alive? What's moving? What's stuck? Emoji-driven health indicators give an instant pulse check.
+- **Anatomy (file-management):** Where is everything? An annotated directory tree with per-folder status turns the filesystem into a map.
+- **Checkup (health-audit):** How healthy is it? Critical issues, security posture, and sustainability assessment tell you what needs attention.
+
+One file. Three lenses. Updated over time.
+
+---
+
+## II. When to Use This Skill
+
+- **Writing a status report:** Monthly, per-release, or ad-hoc — this template gives you the structure.
+- **Onboarding someone to a project:** Instead of a 30-minute walkthrough, hand them a `.status.md`.
+- **Preparing a handoff:** Moving a project between teams or agents? This is the context document.
+- **Before a major decision:** Understanding the full state before deciding what to change.
+- **When a project feels opaque:** Structure reduces confusion. The template imposes coherence on complexity.
+- **After running the `repo-status` skill:** This template is Phase 4 of that workflow.
+
+---
+
+## III. The Template Structure
+
+The status document has 10 sections. Each one has a specific job.
+
+### Section 1: Vision & Purpose
+**Job:** Anchor everything that follows. One sentence + core principles.
+
+Why it matters: Without a stated purpose, status updates become lists of things. With one, they become a story about progress toward a goal.
+
+```markdown
+## 1. Vision & Purpose
+> [One sentence capturing what the project is and why it exists.]
+**Core Principles:** [3-5 comma-separated principles]
+```
+
+### Section 2: Current State
+**Job:** Instant pulse check. A table of major areas with emoji status and brief notes.
+
+Why it matters: Someone glancing at this document for 5 seconds should know if things are healthy or on fire. The emoji table achieves this.
+
+```markdown
+## 2. Current State
+| Area | Status | Notes |
+| :--- | :--- | :--- |
+| **[Major Area]** | ✅/🔄/⚠️/❌ | [One-line note] |
+```
+
+**Status Key:**
+- ✅ Complete/Healthy
+- 🔄 In Progress
+- ⏸️ Paused
+- ⚠️ Concern
+- ❌ Blocked/Critical
+
+### Section 3: Directory Structure
+**Job:** Annotated filesystem map. Every significant directory gets a status emoji and note.
+
+Why it matters: Most codebases lack a visual map of what's where. An annotated tree is worth a thousand words for spatial orientation.
+
+Use `📦` for legacy/deprecated directories. Use `—` for empty or minimal ones.
+
+### Section 4: Semantic Clusters
+**Job:** Group components by *what they do*, not where they live.
+
+Why it matters: This is the behavioral architecture. A feature spans frontend + backend + database + tests. Clusters reveal the system's capabilities as cross-cutting concerns.
+
+If using semantic clusters, invoke the `semantic-clusters` skill for the full framework. Otherwise, this section can be simplified to a feature list with health assessments.
+
+For each cluster:
+```markdown
+### [emoji] [VERB] — [Short Description]
+> [One sentence explaining this capability.]
+| Component | Location | Status | LOC |
+|-----------|----------|--------|-----|
+**Health:** [emoji] [assessment]
+**Audit Notes:** [key technical details]
+```
+
+### Section 5: File Importance Ranking
+**Job:** Rank files by criticality so people know what not to break.
+
+Why it matters: In a 500-file codebase, 10 files are critical, 10 are important, and the rest are supporting. Making this explicit prevents accidental damage to core files.
+
+Four tiers: Critical (system breaks without these), Important (features break), Supporting (graceful degradation), Knowledge (development-time only).
+
+### Section 6: Health Assessment
+**Job:** Honest checkup. Critical issues, security, sustainability.
+
+Why it matters: This is the health-audit perspective. Every project has blind spots — security gaps, test coverage holes, manual processes that should be automated. This section forces them into the light.
+
+Three categories:
+- **Critical Issues:** Can it build? Critical vulnerabilities? Main branch broken?
+- **Security:** Secrets management, auth, encryption, access control.
+- **Sustainability:** Test coverage, CI/CD, tech debt, documentation freshness.
+
+### Section 7: Active Workstreams
+**Job:** What's being worked on right now, by whom.
+
+A table: `Workstream | Owner | Status | Focus`
+
+### Section 8: Blockers & Dependencies
+**Job:** What's preventing progress. Be ruthlessly honest.
+
+If nothing is blocking, say "None." That's valuable information too.
+
+### Section 9: Next Steps
+**Job:** Concrete, actionable items. Numbered list with emoji status.
+
+Not aspirational goals — specific things that should happen next.
+
+### Section 10: Aggregate Statistics
+**Job:** Summary numbers table for quick reference.
+
+LOC, file counts, package counts, test coverage, migration counts, CI/CD workflow counts, versions shipped.
+
+---
+
+## IV. How to Fill the Template
+
+Read `references/complete-template.md` for the full, copy-paste-ready template with all sections, placeholders, and HTML comments for guidance.
+
+**The filling process:**
+
+1. **Start with Section 1.** If you can't write the vision in one sentence, you don't understand the project well enough yet. Go back and read more.
+2. **Fill Section 2 next.** The current state table forces you to identify the major areas. This becomes your map for the rest.
+3. **Sections 3-4 require exploration.** Walk the filesystem, read key files, count LOC. This is the most time-consuming part.
+4. **Section 5 requires judgment.** Which 10 files, if deleted, would break the system? Which 10 more would break major features?
+5. **Section 6 requires honesty.** The health assessment is useless if it's all green. Every project has concerns. Find them.
+6. **Sections 7-9 require current knowledge.** Talk to the team, read recent PRs, check the issue tracker.
+7. **Section 10 is verification.** Run `find` and `wc -l` to get real numbers. Don't guess.
+
+---
+
+## V. Best Practices
+
+- **Dot-prefix the file.** Save as `.status.md` to keep it discoverable but out of the way. It complements (doesn't replace) a lightweight `STATUS.md`.
+- **Update incrementally.** After the first write, subsequent updates should diff against the existing document, not regenerate from scratch.
+- **Emoji consistency.** Use the same status key everywhere. Mixing conventions creates noise.
+- **Be concise in tables.** Each table cell should be scannable in under 3 seconds. Full sentences belong in prose sections, not tables.
+- **The directory tree should be 2-3 levels deep** for most directories, deeper only for architecturally significant subtrees.
+- **Statistics will drift.** Within 10% is accurate enough. Note the date so readers know how fresh the numbers are.
+- **Section 4 is optional for simple projects.** If the project has fewer than 50 files, skip semantic clusters and use a flat feature list instead.
+- **Section 5 is optional for small projects.** Below 100 files, importance ranking adds little value.
+
+---
+
+## VI. Adapting the Template
+
+Not every project needs all 10 sections. Here's a sizing guide:
+
+| Project Size | Sections to Include |
+|-------------|-------------------|
+| **Small** (< 50 files) | 1, 2, 3, 6, 7, 9 |
+| **Medium** (50-300 files) | 1, 2, 3, 4 (simplified), 6, 7, 8, 9, 10 |
+| **Large** (300+ files) | All 10 sections |
+| **Monorepo** | All 10, with sub-sections per package/service |
+
+For non-software projects (documentation sites, design systems, data pipelines), adapt the vocabulary but keep the structure. Section 4 clusters might become "capabilities" or "data flows" instead of "action verbs."
+
+---
+
+## VII. Quality Checklist
+
+Before delivering the `.status.md`, confirm:
+
+- [ ] Vision statement is present, accurate, and one sentence
+- [ ] Current state table covers every major subsystem
+- [ ] Directory tree is annotated with status emojis
+- [ ] Health assessment is honest (not all green)
+- [ ] Active workstreams reflect actual current work (not aspirations)
+- [ ] Blockers section is truthful (empty or populated, not missing)
+- [ ] Next steps are concrete and actionable (not "improve things")
+- [ ] Statistics are programmatically verified (not guessed)
+- [ ] The document reads coherently top-to-bottom
+- [ ] The document is dated with `Last Updated`
+---
+
+## OpenClaw Tool Integration
+
+When running inside the Dojo Genesis plugin:
+
+1. **Start** by calling `dojo_get_context` to retrieve full project state, history, and artifacts
+2. **During** the skill, follow the workflow steps documented above
+3. **Save** outputs using `dojo_save_artifact` with the `artifacts` output directory
+4. **Update** project state by calling `dojo_update_state` to record skill completion and any phase transitions
+

package/skills/status-template/claw.json

@@ -0,0 +1,12 @@
+{
+  "name": "dojo-genesis-plugin-status-template",
+  "version": "1.0.0",
+  "description": "Write status docs using 10-section template",
+  "author": "dojo-genesis",
+  "license": "MIT",
+  "permissions": [],
+  "entry": "SKILL.md",
+  "tags": ["dojo-genesis", "orchestration", "system", "health"],
+  "models": ["claude-*", "gpt-*", "gemini-*"],
+  "minOpenClawVersion": "2026.1.0"
+}

package/skills/status-template/references/complete-template.md

@@ -0,0 +1,191 @@
+# Complete .status.md Template
+
+**Purpose:** Copy this template and fill in every section. Delete all HTML comments and placeholders before saving.
+
+---
+
+```markdown
+# [Project Name] — Comprehensive System Status
+
+**Author:** [Who generated this]
+**Status:** [Active & Evolving | On Hold | Complete]
+**Last Updated:** [YYYY-MM-DD]
+**Methodology:** status-template skill (status-writing + file-management + health-audit)
+
+---
+
+## 1. Vision & Purpose
+
+> [One compelling sentence capturing what this project is and why it exists.]
+
+**Core Principles:** [3-5 comma-separated principles, e.g., Privacy-first, Observable, Adaptive]
+
+---
+
+## 2. Current State
+
+| Area | Status | Notes |
+| :--- | :--- | :--- |
+| **[Major Area 1]** | [emoji] | [Brief note] |
+| **[Major Area 2]** | [emoji] | [Brief note] |
+| **[Major Area 3]** | [emoji] | [Brief note] |
+
+**Status Key:**
+- ✅ **Complete/Healthy:** Done and verified.
+- 🔄 **In Progress:** Actively being worked on.
+- ⏸️ **Paused:** Intentionally on hold.
+- ⚠️ **Concern:** Needs attention but not blocking.
+- ❌ **Blocked/Critical:** Halted or failing.
+
+---
+
+## 3. Directory Structure & Folder Status
+
+```
+project-root/                          [emoji] [short note]
+├── [dir1]/                            [emoji] [note]
+│   ├── [subdir1]/                     [emoji] [note]
+│   └── [subdir2]/                     [emoji] [note]
+├── [dir2]/                            [emoji] [note]
+│   └── [subdir]/                      [emoji] [note]
+├── [file1.ext]                        [emoji] [note]
+└── [file2.ext]                        [emoji] [note]
+```
+
+---
+
+## 4. Semantic Action-Verb Clusters
+
+<!-- Use the semantic-clusters skill for the full framework.
+     For simpler projects, replace with a flat feature list. -->
+
+### [emoji] [VERB] — [Short Description]
+
+> [One sentence explaining what this capability means for the system.]
+
+| Component | Location | Status | LOC |
+|-----------|----------|--------|-----|
+| [Name] | [path/to/component/] | [emoji] | [number] |
+
+**Health:** [emoji] [1-line assessment]
+**Audit Notes:** [Key technical details, 1-2 lines max.]
+
+---
+
+<!-- Repeat for each cluster. -->
+
+### Cross-Cluster Components
+
+| Component | Directory | Primary Cluster | Notes |
+|-----------|-----------|----------------|-------|
+| [Name] | [path/] | [VERB] | [Why it's cross-cluster] |
+
+---
+
+## 5. File Importance Ranking
+
+### Tier 1 — Critical (System won't function without these)
+
+| Rank | File | Why |
+|------|------|-----|
+| 1 | [path/to/file] | [One-line justification] |
+
+### Tier 2 — Important (Core features break without these)
+
+| Rank | File | Why |
+|------|------|-----|
+| 11 | [path/to/file] | [One-line justification] |
+
+### Tier 3 — Supporting (Degrade gracefully without these)
+
+| Rank | File | Why |
+|------|------|-----|
+| 21-25 | [path/to/files] | [Category description] |
+
+### Tier 4 — Knowledge (Essential for development, not runtime)
+
+| Rank | File | Why |
+|------|------|-----|
+| 51 | [path/to/file] | [One-line justification] |
+
+---
+
+## 6. Health Assessment
+
+### Critical Issues
+- **[None / List issues]**
+
+### Security
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Secret management | [emoji] | [Assessment] |
+| Authentication | [emoji] | [Assessment] |
+| Authorization | [emoji] | [Assessment] |
+| Encryption | [emoji] | [Assessment] |
+
+### Sustainability
+
+| Area | Status | Notes |
+|------|--------|-------|
+| Backend test coverage | [emoji] | [Percentage + assessment] |
+| Frontend test coverage | [emoji] | [Percentage + assessment] |
+| CI/CD automation | [emoji] | [Workflow count + assessment] |
+| Technical debt | [emoji] | [Assessment] |
+| Documentation | [emoji] | [File count + assessment] |
+| Manual processes | [emoji] | [List any] |
+
+---
+
+## 7. Active Workstreams
+
+| Workstream | Owner/Agent | Status | Focus |
+|------------|-------------|--------|-------|
+| [Name] | [Who] | [emoji] | [What they're doing] |
+
+---
+
+## 8. Blockers & Dependencies
+
+- **[Blocker description]** — [Impact and who owns resolution]
+
+---
+
+## 9. Next Steps
+
+1. [emoji] [Concrete, actionable task]
+2. [emoji] [Concrete, actionable task]
+3. [emoji] [Concrete, actionable task]
+
+---
+
+## 10. Aggregate Statistics
+
+| Metric | Value |
+|--------|-------|
+| Total [primary language] LOC | ~[number] |
+| Total [primary language] files | [number] |
+| Total [secondary language] LOC | ~[number] |
+| Total [secondary language] files | [number] |
+| Total [tools/endpoints] | [number] |
+| Total documentation files | [number] |
+| Total migrations | [number] |
+| Total CI/CD workflows | [number] |
+| Versions shipped | [number] |
+
+---
+```
+
+---
+
+## Template Notes
+
+1. **Delete all HTML comments** before saving the final document.
+2. **Adapt section count to project size:**
+   - Small (< 50 files): Sections 1, 2, 3, 6, 7, 9
+   - Medium (50-300 files): Sections 1-3, 4 (simplified), 6-10
+   - Large (300+ files): All 10 sections
+3. **Emoji status key must be consistent** across all sections.
+4. **LOC is approximate.** Use `~` prefix. Within 10% accuracy is fine.
+5. **Directory tree depth:** 2-3 levels default, deeper for architecturally significant areas.
+6. **Cross-cluster table** (Section 4) is only needed when using semantic action-verb clusters. For simpler projects using a flat feature list, skip it.

package/skills/status-writing/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: status-writing
+description: Write and update STATUS.md files to provide at-a-glance visibility into project health as a single source of truth. Use at project start, during weekly syncs, after major releases, or whenever project status significantly changes. Trigger phrases: 'create a status file', 'update the project status', 'what's the current state', 'document where we are', 'create a status dashboard'.
+---
+
+> **OpenClaw Integration:** This skill is invoked by the Dojo Genesis plugin via `/dojo run status-writing`.
+> The agent receives project context automatically via the `before_agent_start` hook.
+> Use `dojo_get_context` for full state, `dojo_save_artifact` to persist outputs,
+> and `dojo_update_state` to record phase transitions and decisions.
+
+# Status Writer Skill
+
+**Version:** 1.0  
+**Created:** 2026-02-04  
+**Author:** Manus AI  
+**Purpose:** To provide a structured, repeatable process for writing and updating `STATUS.md` files, turning project tracking into a mindful and transparent practice.
+
+---
+
+## I. The Philosophy: The Ritual of Bearing Witness
+
+A `STATUS.md` file is more than a report; it is a **Ritual of Bearing Witness**. It is a practice of radical honesty about where a project truly is—not where we wish it were, or where it is supposed to be. It is a pause to see clearly, without judgment, the current state of our work.
+
+This ritual combats the natural tendency for entropy and confusion to creep into complex projects. It provides a single, trusted source of truth that grounds our conversations and decisions in reality. By maintaining this document with care, we cultivate transparency, accountability, and a shared understanding of our journey.
+
+---
+
+## II. When to Use This Skill
+
+-   **At the beginning of a new project:** To establish the initial state and vision.
+-   **At the start and end of a work session:** To frame the day's work and document its outcome.
+-   **During a weekly sync:** To facilitate a high-level review of all active projects.
+-   **Whenever there is a significant change in project status:** (e.g., a new blocker emerges, a major milestone is reached).
+
+---
+
+## III. The Status Update Workflow
+
+### Step 1: Locate or Create the `STATUS.md` File
+
+Navigate to the root of the project repository. If a `STATUS.md` file does not exist, create one using the template from Section IV of this skill.
+
+### Step 2: Update the Header
+
+Change the `Last Updated` date to the current date.
+
+### Step 3: Review and Update Each Section
+
+Go through each section of the `STATUS.md` file and update it to reflect the current reality.
+
+-   **Vision & Purpose:** This should rarely change, but it is good to re-read it to stay grounded.
+-   **Current State:** This is the most important section. Update the status of each area using the emoji key (✅, 🔄, ⏸️, ❌). Add or remove items as the project evolves.
+-   **Active Workstreams:** What are you actively working on *right now*? Update the tasks and progress.
+-   **Blockers & Dependencies:** Be ruthlessly honest about what is preventing progress. If a blocker is resolved, remove it.
+-   **Next Steps:** What is the immediate next action? This should be concrete and actionable.
+
+### Step 4: Commit the Changes
+
+Commit the updated `STATUS.md` file with a clear and descriptive commit message.
+
+**Commit Message Convention:**
+`docs(status): Update [Project Name] status for [Date]`
+
+**Example:**
+`docs(status): Update AROMA status for 2026-02-04`
+
+---
+
+## IV. `STATUS.md` Template
+
+```markdown
+# [Project Name] Project Status
+
+**Author:** [Your Name]
+**Status:** [Active & Evolving | On Hold | Complete]
+**Last Updated:** [YYYY-MM-DD]
+
+---
+
+## 1. Vision & Purpose
+
+> [A single, compelling sentence that captures the essence of this project.]
+
+**Core Principles:**
+-   [Principle 1]
+-   [Principle 2]
+-   [Principle 3]
+
+---
+
+## 2. Current State
+
+[A brief, high-level summary of the project's current phase or condition.]
+
+| Area | Status | Notes |
+| :--- | :--- | :--- |
+| **[Key Area 1]** | [✅/🔄/⏸️/❌] | [Brief, relevant notes.] |
+| **[Key Area 2]** | [✅/🔄/⏸️/❌] | [Brief, relevant notes.] |
+| **[Key Area 3]** | [✅/🔄/⏸️/❌] | [Brief, relevant notes.] |
+
+**Status Key:**
+-   ✅ **Complete:** The work is done and verified.
+-   🔄 **In Progress:** Actively being worked on.
+-   ⏸️ **Paused:** Intentionally on hold.
+-   ❌ **Blocked:** Progress is halted due to a dependency or issue.
+
+---
+
+## 3. Active Workstreams
+
+[What are we actively working on right now? Be specific.]
+
+1.  **[Workstream 1]:**
+    -   **Task:** [Description of the current task.]
+    -   **Progress:** [e.g., 75% complete, waiting for review]
+
+2.  **[Workstream 2]:**
+    -   **Task:** [Description of the current task.]
+    -   **Progress:** [e.g., Just started, gathering requirements]
+
+---
+
+## 4. Blockers & Dependencies
+
+[What is preventing progress? Be ruthlessly honest.]
+
+-   **[Blocker 1]:** [Description of the blocker and its impact.]
+    -   **Owner:** [Who is responsible for resolving this?]
+    -   **Next Step:** [What is the next action to resolve this?]
+
+---
+
+## 5. Next Steps
+
+[What are the immediate next actions for this project?]
+
+1.  [A concrete, actionable task.]
+2.  [A concrete, actionable task.]
+3.  [A concrete, actionable task.]
+```
+
+---
+
+## V. Best Practices
+
+-   **Be Honest:** The value of this document is its truthfulness. Do not sugarcoat bad news.
+-   **Be Concise:** Use bullet points and short sentences. This is a dashboard, not a novel.
+-   **Use the Emoji Key:** The emojis provide an instant visual summary of project health.
+-   **Update Regularly:** A stale status document is worse than no status document. Make it a habit.
+-   **Focus on the 'What', Not the 'Who':** The status is about the project, not the people. Frame blockers and issues impersonally.
+---
+
+## OpenClaw Tool Integration
+
+When running inside the Dojo Genesis plugin:
+
+1. **Start** by calling `dojo_get_context` to retrieve full project state, history, and artifacts
+2. **During** the skill, follow the workflow steps documented above
+3. **Save** outputs using `dojo_save_artifact` with the `artifacts` output directory
+4. **Update** project state by calling `dojo_update_state` to record skill completion and any phase transitions
+

package/skills/status-writing/claw.json

@@ -0,0 +1,12 @@
+{
+  "name": "dojo-genesis-plugin-status-writing",
+  "version": "1.0.0",
+  "description": "Write and update STATUS.md files",
+  "author": "dojo-genesis",
+  "license": "MIT",
+  "permissions": [],
+  "entry": "SKILL.md",
+  "tags": ["dojo-genesis", "orchestration", "system", "health"],
+  "models": ["claude-*", "gpt-*", "gemini-*"],
+  "minOpenClawVersion": "2026.1.0"
+}