| name | status-template |
| description | Produces a comprehensive `.status.md` file using a 10-section schema that bridges heartbeat (current state), anatomy (directory structure), and checkup (health assessment) perspectives into one document. The formal 10-section schema itself. For a first exploration-heavy snapshot of an unfamiliar repo, use `repo-status`; for routinely updating an existing STATUS.md, use `status-writing`. Use when: "write a status report", "give me the lay of the land", "where are we right now", "prepare a handoff document", "document the current codebase state". |
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.
## 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.
## 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:
### [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:
- 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.
- Fill Section 2 next. The current state table forces you to identify the major areas. This becomes your map for the rest.
- Sections 3-4 require exploration. Walk the filesystem, read key files, count LOC. This is the most time-consuming part.
- Section 5 requires judgment. Which 10 files, if deleted, would break the system? Which 10 more would break major features?
- Section 6 requires honesty. The health assessment is useless if it's all green. Every project has concerns. Find them.
- Sections 7-9 require current knowledge. Talk to the team, read recent PRs, check the issue tracker.
- 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:
Output
.status.md at the project root with all applicable sections from the 10-section schema. Section count adapts to project size (small projects use 6 sections; large projects use all 10).- The file complements but does not replace a lightweight
STATUS.md — .status.md is the comprehensive agent-facing audit; STATUS.md is the human-facing dashboard.
Examples
Scenario 1: "Create a project overview before a strategy session" → .status.md produced with all 10 sections. Vision and Purpose anchors everything. Current State table reveals 2 blocked areas. Health assessment honestly flags no CI/CD and 8% test coverage as sustainability concerns.
Scenario 2: "Prepare a handoff doc for the incoming agent" → .status.md covers a 120-file project. Sections 4 (Semantic Clusters) and 5 (File Importance Ranking) included. Incoming agent reads the document instead of spending 30 minutes on discovery.
Edge Cases
- For projects under 50 files, skip Sections 4 and 5 (clusters and importance ranking) — they add little value at small scale, and the overhead of generating them exceeds the benefit.
- For monorepos, use all 10 sections with sub-sections per package or service under each primary section.
Anti-Patterns
- Treating the Current State table as aspirational — the emoji indicators must reflect actual verified state, not what the team wishes were true.
- Generating statistics from memory or rough estimates — run
find and wc -l to get real numbers; within 10% is accurate enough, but guessing is not.
Related Skills
semantic-clusters — provides the full methodology for Section 4; invoke it before filling that section for any project with 50+ filesrepo-context-sync — use to sync and map the codebase before filling Sections 3 and 10; prevents stale-inventory errorshealth-audit — deep security and sustainability assessment that feeds Section 6 with concrete findings rather than guessesconvergence-gate — produce a .status.md at the end of each convergence session to capture the settled state as a handoff artifact
