Produces a comprehensive `.status.md` status document combining filesystem exploration, semantic clusters, file importance ranking, and health assessment — a single artifact any agent or human can use as the starting point for a project. Use when: 'give me a complete repo overview', 'understand this codebase', 'create a system map', 'build a mental model', 'prepare a handoff document'.
Produces a comprehensive `.status.md` status document combining filesystem exploration, semantic clusters, file importance ranking, and health assessment — a single artifact any agent or human can use as the starting point for a project. Use when: 'give me a complete repo overview', 'understand this codebase', 'create a system map', 'build a mental model', 'prepare a handoff document'.
category
system-health
triggers
["give me a complete repo overview","understand this codebase","create a system map","build a mental model","prepare a handoff document"]
tier
1
agents
["primary"]
tool_dependencies
["file_system"]
inputs
[{"name":"repo_path","type":"string","description":"Path to the repository to generate a status document for","required":true}]
outputs
[{"name":"status_document","type":"ref","format":"cas-ref","description":"Comprehensive .status.md combining filesystem exploration, semantic clusters, file importance ranking, and health assessment"}]
Repo Status Skill
Version: 1.0
Created: 2026-02-08
Author: Cruz + Manus (Cowork)
Origin: Codified from a live repo-context-sync + strategic-scout + status-writing session on Dojo Genesis.
Lineage: status-writing + file-management + health-audit, distilled into a single repeatable workflow.
I. The Philosophy: See the Whole Before Touching a Part
Most codebases are explored piecemeal — someone reads a file, then another, then another, building a fragmentary picture that drifts as the project evolves. This skill takes the opposite approach: see the whole system first, as a living organism, then record what you see in a structured artifact that any future agent or human can use as a starting point.
The output is a .status.md file — a comprehensive, versioned snapshot that bridges three perspectives:
Status Writer: Emoji-driven health indicators, workstream tracking, blockers, next steps. The "heartbeat" view.
File Management: Annotated directory tree with per-folder status. The "anatomy" view.
Health Supervisor: Critical/security/sustainability assessment. The "checkup" view.
A single document. One place to look. Updated over time like a living record.
II. When to Use This Skill
Onboarding to a new project: Before writing a single line, run this skill to build your mental model.
Periodic health check: Monthly or per-release, re-run to track drift and detect decay.
Before a major refactor: Understand what exists before deciding what to change.
When handing off context: Give another agent or team member a single file that tells them everything.
When a project feels "big" or "messy": Structure reduces anxiety. This skill imposes structure on chaos.
III. The Workflow
This is a 5-phase process. Each phase builds on the previous one.
Phase 1: Grounding (Read Before You Judge)
Objective: Understand what the project is before evaluating how well it works.
Time budget: ~30% of total effort. Parallelize aggressively.
Phase 3: Semantic Clustering
Objective: Group everything by what the system does, not where files happen to live.
This is the distinctive step. Instead of just listing directories, map every feature to an action verb — a cluster that describes a behavioral capability of the system.
Read references/semantic-clusters.md for the full cluster framework and examples.
The process:
Review the inventory from Phase 2.
For each significant component, ask: "What verb describes what this does?"
Assign it to a cluster. Create new clusters if needed.
For each cluster, build a component table: Component | Location | Status | LOC
Write a health assessment per cluster.
Identify cross-cluster components (things that serve multiple verbs).
Identify orphans (components that don't fit any cluster) — these may signal architectural confusion.
Time budget: ~25% of total effort. This is where the insight lives.
Phase 4: Write the .status.md
Objective: Assemble everything into a single, structured document.
Read references/status-template.md for the complete output template.
Be honest. Use emoji status indicators: ✅ good, ⚠️ concern, ❌ blocked.
VII. Best Practices
Dot-prefix the output file..status.md stays discoverable but doesn't clutter the root alongside README and STATUS.
Separate from STATUS.md. The lightweight STATUS.md (per status-writing skill) is the human-facing dashboard. .status.md is the comprehensive agent-facing audit. They complement each other.
Update incrementally. After the first generation, subsequent runs should diff against the existing .status.md and update rather than regenerate from scratch.
Statistics drift is normal. LOC counts change every commit. The goal is "accurate enough to be useful" — within 10% is fine.
Semantic clusters are the crown jewel. The directory tree tells you where things are. The clusters tell you what things do. Prioritize cluster quality over tree completeness.
Parallelize Phase 2. The deep inventory is the slowest phase. Use subagents or parallel exploration to cut time.
Verification is not optional. A beautiful document full of wrong numbers is worse than no document. Always verify.
VIII. Quality Checklist
Before delivering the .status.md, confirm:
Vision statement is present and accurate
Every major directory appears in the annotated tree
Every significant component maps to at least one semantic cluster
No orphan directories (unmapped components) remain unexplained
File importance ranking has at least 10 Tier 1-2 files
Health assessment covers critical, security, and sustainability
Aggregate statistics are programmatically verified (within 10%)
Active workstreams reflect actual current work
Next steps are concrete and actionable
The document reads coherently from top to bottom
Output
.status.md saved at the project root (dot-prefixed, stays discoverable without cluttering the root alongside README).
Ten sections: Vision and Purpose, Current State (emoji table), Directory Structure (annotated tree), Semantic Clusters (per-verb component tables), File Importance Ranking (4 tiers), Health Assessment, Active Workstreams, Blockers and Dependencies, Next Steps, Aggregate Statistics.
Examples
Scenario 1: "Give me a complete overview of the Gateway repo before the sprint" → .status.md generated with all 10 sections. Semantic clusters reveal REASON and ORCHESTRATE are the most complex clusters. Health assessment surfaces a missing CI/CD config as a sustainability concern.
Scenario 2: "Prepare a handoff doc for the HTMLCraft Studio" → .status.md produced for a Wails v2 + Go project. 8-module architecture mapped into 5 clusters. Tier 1 files identified. Handed off to incoming agent who begins from the status doc rather than a 30-minute walkthrough.
Edge Cases
If the project has fewer than 50 files, skip semantic clusters (Section 4) and file importance ranking (Section 5) — they add little value at small scale.
On subsequent runs, diff against the existing .status.md and update incrementally rather than regenerating from scratch — especially critical for aggregate statistics that change with every commit.
Anti-Patterns
Conflating this skill with health-audit — repo-status produces status documents; health-audit produces engineering commissions. The outputs are complementary but distinct.
Verifying statistics by estimation rather than running find and wc -l — a beautiful document full of wrong numbers is worse than no document.
