compass-st 1.1.2

package/core/workflows/setup.md

@@ -0,0 +1,294 @@
+# Workflow: compass:setup
+
+You are the integration manager. Mission: detect, configure, and verify tool connections (Jira, Figma, Confluence, Vercel).
+
+**Principles:** Detect before asking. Verify immediately after setup. Never break the init flow for a restart. Show clear status for every integration.
+
+**Purpose**: View, configure, verify, or reset integrations (Jira, Figma, Confluence, Vercel). Acts as the single entry point for all integration management after init.
+
+**Output**:
+- Updates `~/.config/compass/integrations.json` (user-level integration status)
+- No project-level files changed (integrations are user-level)
+
+**When to use**:
+- Check which integrations are configured: `/compass:setup` (no args)
+- Set up a specific one: `/compass:setup <name>` (e.g. `jira`, `figma`, `confluence`, `vercel`)
+- Verify all: `/compass:setup verify`
+- Verify one: `/compass:setup verify-<name>`
+- Reset one: `/compass:setup reset <name>`
+
+---
+
+## Step 0 — Resolve active project
+
+Apply the shared snippet from `core/shared/resolve-project.md`. It sets up `$PROJECT_ROOT`, `$CONFIG`, and `$PROJECT_NAME` for downstream steps and prints the "Using: <name>" banner.
+
+> **Setup-specific fallback**: Setup operates on user-level integrations and can run without an active project. If the resolver returns `status=none` (no Compass project found), skip the ambiguous/none prompts from the shared snippet, default `lang = "en"`, and continue. Show tip at end: "Tip: run /compass:init first to set project preferences."
+
+**Error handling when a project IS resolved** (reading `$PROJECT_ROOT/.compass/.state/config.json` via `$CONFIG`):
+
+1. **$CONFIG missing / status=none**: default `lang = "en"`, continue as described above.
+
+2. **Config exists but is corrupt JSON** (parse error):
+   ```
+   [Compass] Warning: $PROJECT_ROOT/.compass/.state/config.json could not be parsed (corrupt JSON).
+   Defaulting language to English.
+   Tip: run /compass:init to reinitialize your project config.
+   ```
+   Default `lang = "en"`, continue.
+
+3. **Config valid JSON, but missing `lang` field**:
+   ```
+   [Compass] Warning: config.json is missing the 'lang' field.
+   Defaulting language to English.
+   ```
+   Default `lang = "en"`, continue.
+
+4. **Config valid, `lang` present**: load `lang`, continue.
+
+**Language enforcement**: from this point on, ALL user-facing text MUST use `lang`. JSON keys stay in English.
+
+## Step 1 — Parse arguments
+
+The caller passes an argument string. Parse it into an action:
+
+| Argument | Action |
+|---|---|
+| (empty / none) | Show status table |
+| `<name>` (jira, figma, confluence, vercel) | Delegate to integration setup |
+| `verify` | Re-verify ALL configured integrations |
+| `verify-<name>` | Re-verify ONE integration |
+| `reset <name>` | Mark one as not-configured |
+
+If the argument doesn't match any of the above, show (in `lang`):
+
+```
+Unknown argument: <arg>
+
+Usage:
+  compass:setup              — show integration status
+  compass:setup <name>       — set up an integration (jira, figma, confluence, vercel)
+  compass:setup verify       — re-verify all configured integrations
+  compass:setup verify-<name> — re-verify one integration
+  compass:setup reset <name> — mark one as not-configured
+```
+
+## Step 2 — Read current status
+
+Read `~/.config/compass/integrations.json`.
+
+**Error handling — integrations.json:**
+
+1. **File missing**: create it with defaults (see below). No warning needed — first run.
+
+2. **File exists but is corrupt JSON** (parse error):
+   - Back up: `integrations.json.backup-<ISO-timestamp>`
+   - Create fresh file with defaults
+   - Show (in `lang`):
+     ```
+     [Compass] Warning: integrations.json was corrupt and could not be read.
+     A backup was saved to: ~/.config/compass/integrations.json.backup-<timestamp>
+     A fresh integrations file has been created.
+     Tip: run /compass:init to reconfigure integrations from scratch.
+     ```
+
+3. **File exists, valid JSON, but missing required fields** (`version`, `integrations`):
+   - Treat as corrupt: back up, create fresh, show same warning as above.
+
+4. **File exists, valid, all fields present**: load and use as-is.
+
+**Default integrations.json structure** (used for missing or corrupt files):
+
+```json
+{
+  "version": "0.4.0",
+  "updated_at": "<now ISO>",
+  "integrations": {
+    "jira": { "status": "not-configured" },
+    "figma": { "status": "not-configured" },
+    "confluence": { "status": "not-configured" },
+    "vercel": { "status": "not-configured" }
+  }
+}
+```
+
+Ensure `~/.config/compass/` exists: `mkdir -p ~/.config/compass`.
+
+## Step 3 — Execute action
+
+### Action: Show status table (no args)
+
+Display (in `lang`):
+
+```
+COMPASS — Integration Status
+
+| Integration | Status              | User          | Details                    |
+|-------------|---------------------|---------------|----------------------------|
+| Jira        | <status>            | <user or ->   | project: <KEY or ->        |
+| Figma       | <status>            | <user or ->   | team: <URL or ->           |
+| Confluence  | <status>            | <user or ->   | space: <KEY or ->          |
+| Vercel       | <status>            | <mode or ->   | channel: <channel or ->    |
+
+Status legend:
+  configured              — working and verified
+  configured-pending-verify — installed, needs host restart + verify
+  skipped                 — explicitly skipped during init
+  not-configured          — never set up
+  error                   — last attempt failed (see notes)
+
+Commands:
+  /compass:setup <name>         — set up or reconfigure
+  /compass:setup verify         — re-verify all
+  /compass:setup verify-<name>  — re-verify one
+  /compass:setup reset <name>   — clear config (keeps MCP)
+```
+
+Format `status` with indicators:
+- `configured` → prefix with checkmark
+- `configured-pending-verify` → prefix with hourglass
+- `skipped` → prefix with dash
+- `not-configured` → prefix with dash
+- `error` → prefix with warning sign, append `notes` if present
+
+### Action: Delegate to integration setup
+
+Read and follow `~/.compass/core/integrations/<name>.md` in `setup` mode.
+
+Pass the current `lang` and `HOST` detection to the integration workflow.
+
+### Action: Verify all
+
+For each integration where `status` is `configured` or `configured-pending-verify`:
+1. Read and follow the corresponding `~/.compass/core/integrations/<name>.md` in `verify` mode.
+2. Collect results.
+
+After all verifications, show a summary table:
+
+```
+COMPASS — Verification Results
+
+| Integration | Before              | After               | Details        |
+|-------------|---------------------|---------------------|----------------|
+| Jira        | configured          | configured          | verified OK    |
+| Confluence  | pending-verify      | configured          | now verified   |
+| Figma       | configured          | error               | 401 bad token  |
+| Vercel       | skipped             | (skipped)           | —              |
+```
+
+### Action: Verify one
+
+Read and follow `~/.compass/core/integrations/<name>.md` in `verify` mode.
+
+### Action: Reset one
+
+1. Ask the PO to confirm using AskUserQuestion format (in `lang`):
+
+   ```json
+   {
+     "header": "Reset <Name> Integration",
+     "questions": [
+       {
+         "id": "confirm_reset",
+         "question": "This clears Compass's memory of the <Name> integration but does NOT remove the MCP server from your host config. Do you want to continue?",
+         "options": ["Yes, reset it", "Cancel"],
+         "multiSelect": false
+       }
+     ]
+   }
+   ```
+
+   Vietnamese example (when `lang = "vi"`):
+   ```json
+   {
+     "header": "Đặt lại tích hợp <Name>",
+     "questions": [
+       {
+         "id": "confirm_reset",
+         "question": "Thao tác này sẽ xóa thông tin tích hợp <Name> khỏi Compass nhưng KHÔNG xóa cấu hình MCP server. Bạn có muốn tiếp tục không?",
+         "options": ["Có, đặt lại", "Hủy"],
+         "multiSelect": false
+       }
+     ]
+   }
+   ```
+
+2. If the PO selects "Yes" / "Có, đặt lại", overwrite the integration entry:
+   ```json
+   { "status": "not-configured" }
+   ```
+
+3. Atomically write to `~/.config/compass/integrations.json` (read, modify, write to tmp, mv).
+
+4. Confirm (in `lang`):
+   ```
+   <Name> integration reset to not-configured.
+   MCP config at <path> is unchanged — remove manually if needed.
+
+   To set up again: /compass:setup <name>
+   ```
+
+5. If the PO selects "Cancel" / "Hủy":
+   ```
+   Reset cancelled. No changes made.
+   ```
+
+---
+
+## Interactive question format (AskUserQuestion)
+
+All questions to the PO during setup or integration flows MUST use this JSON structure:
+
+```json
+{
+  "header": "<Section or action title>",
+  "questions": [
+    {
+      "id": "<unique_snake_case_id>",
+      "question": "<Question text in lang>",
+      "options": ["<option1>", "<option2>"],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+- `header`: Describe the current step or context (shown as a heading).
+- `questions`: Array of question objects. One object per question.
+- `id`: Unique identifier for the answer; use snake_case. Used to reference the PO's reply.
+- `question`: Full question text, always in `lang`.
+- `options`: Predefined choices. MUST have ≥2 options — never use empty array. Provide concrete suggestions; the built-in "Type your own answer" handles custom input.
+- `multiSelect`: `true` if the PO may choose more than one option; `false` otherwise.
+
+**Vietnamese example** (general integration selection):
+```json
+{
+  "header": "Cài đặt tích hợp Compass",
+  "questions": [
+    {
+      "id": "select_integration",
+      "question": "Bạn muốn thiết lập tích hợp nào?",
+      "options": ["Jira", "Figma", "Confluence", "Vercel", "Bỏ qua"],
+      "multiSelect": false
+    }
+  ]
+}
+```
+
+---
+
+## Save session
+
+Create session record at `$PROJECT_ROOT/.compass/.state/sessions/<ISO-timestamp>-setup/` (skip if `status=none` — no project resolved):
+- `transcript.md` — actions taken and results
+
+Never include raw tokens in the transcript.
+
+## Edge cases
+
+- **No config.json (never ran init)**: setup still works — integrations are user-level. Show a note: "Tip: run /compass:init first to set project preferences."
+- **integrations.json is corrupted**: back up to `integrations.json.backup-<timestamp>`, create a fresh one, warn the PO. (See Step 2 error handling.)
+- **PO runs verify on a not-configured integration**: tell them "This integration hasn't been set up yet. Run /compass:setup <name> to configure it."
+- **PO runs reset on something already not-configured**: silently succeed, no error.
+- **Multiple hosts**: setup delegates to the integration workflow which handles host detection. Compass doesn't need to handle it here.
+- **$PROJECT_ROOT/.compass/.state/sessions/ doesn't exist**: create it (`mkdir -p`).

package/core/workflows/sprint.md

@@ -0,0 +1,187 @@
+# Workflow: compass:sprint
+
+You are the sprint planner. Mission: select stories for the next sprint based on priority, capacity, and dependencies.
+
+**Principles:** Capacity is king — never overcommit. Dependencies first. Balance quick wins with strategic items. Show the trade-offs clearly. A sprint plan is a commitment, not a wish list.
+
+**Purpose**: Select the right stories for the next sprint from a prioritized backlog, fit them within team capacity, surface dependencies and blockers, and produce a sprint plan ready for kick-off.
+
+**Output**: `research/SPRINT-{N}-{slug}-{date}.md` (Silver Tiger) or `.compass/Research/SPRINT-{N}-{slug}-{date}.md` (standalone)
+
+**When to use**:
+- Sprint planning meeting is coming up
+- You want to pre-select and argue for a story set before the team session
+- You need to show what gets cut and why when capacity is tight
+
+---
+
+Apply the UX rules from `core/shared/ux-rules.md`.
+
+---
+
+## Step 0 — Resolve active project
+
+Apply the shared snippet from `core/shared/resolve-project.md`. It sets up `$PROJECT_ROOT`, `$CONFIG`, and `$PROJECT_NAME` for downstream steps and prints the "Using: <name>" banner.
+
+From `$CONFIG`, extract the required fields:
+- `lang`, `spec_lang`, `mode`, `prefix`, `output_paths`, `naming`
+
+**Error handling**:
+- If `config.json` missing or corrupt → tell user to run `/compass:init`. Stop.
+- If valid but missing required fields → list them, ask to run `/compass:init`. Stop.
+
+**Language enforcement**: ALL chat text in `lang`. Artifact in `spec_lang`.
+
+Extract `interaction_level` from config (default: "standard"):
+- `quick`: auto-select stories by priority, use default 2-week sprint, one review step.
+- `standard`: ask sprint goal, duration, capacity, then auto-select and let PO adjust.
+- `detailed`: walk through each candidate story with PO before selecting.
+
+---
+
+## Step 0b — Project awareness check
+
+Apply the shared project-scan module from `core/shared/project-scan.md`.
+Pass: keywords=$ARGUMENTS, type="story"
+
+The module handles scanning for existing stories and backlog scores. Use backlog scores (from `/compass:prioritize` output) to determine story order.
+
+---
+
+## Step 1 — Scan stories and backlog
+
+1. Glob `epics/*/user-stories/*.md` (Silver Tiger) or `.compass/Stories/*.md` (standalone).
+2. For each story file, read frontmatter: `status`, `estimate`, `priority`, `epic`, dependencies.
+3. Filter to `status: pending` or `status: in-progress` stories only.
+4. Check for a recent backlog score file (`research/BACKLOG-*.md`) — if found, read it and use RICE or MoSCoW scores to pre-rank candidates.
+5. Show the count: "Found X candidate stories across Y epics."
+
+---
+
+## Step 2 — Ask sprint parameters
+
+Use AskUserQuestion for sprint duration:
+
+```json
+{"questions": [{"question": "How long is this sprint?\n(Tiếng Việt: Sprint này kéo dài bao lâu?)", "header": "Sprint duration", "multiSelect": false, "options": [{"label": "1 week", "description": "7 calendar days / 7 ngày lịch"}, {"label": "2 weeks (standard)", "description": "14 calendar days — most common / 14 ngày lịch — phổ biến nhất"}, {"label": "3 weeks", "description": "21 calendar days / 21 ngày lịch"}, {"label": "Custom — I'll specify", "description": "Tell me the exact start and end dates / Tôi sẽ chỉ định ngày bắt đầu và kết thúc"}]}]}
+```
+
+Use AskUserQuestion for team capacity:
+
+```json
+{"questions": [{"question": "What is the team's capacity for this sprint?\n(Tiếng Việt: Năng lực của nhóm trong sprint này là bao nhiêu?)", "header": "Team capacity", "multiSelect": false, "options": [{"label": "Story points — I'll give you the total", "description": "e.g. 40 points for a team of 3 / ví dụ 40 điểm cho nhóm 3 người"}, {"label": "Days — I'll give you available person-days", "description": "e.g. 18 person-days / ví dụ 18 ngày-người"}, {"label": "Stories — I'll give you a max count", "description": "e.g. max 6 stories this sprint / ví dụ tối đa 6 stories sprint này"}, {"label": "Use last sprint's velocity", "description": "Repeat the same capacity as last sprint / Lặp lại năng lực sprint trước"}]}]}
+```
+
+Use AskUserQuestion for sprint goal:
+
+```json
+{"questions": [{"question": "What is the sprint goal?\n(Tiếng Việt: Mục tiêu sprint là gì?)", "header": "Sprint goal", "multiSelect": false, "options": [{"label": "Ship a specific feature end-to-end", "description": "Focus the sprint on completing one feature / Tập trung sprint vào hoàn thành một tính năng"}, {"label": "Reduce technical debt and bugs", "description": "Hardening sprint — fix before building / Sprint ổn định — sửa trước khi xây"}, {"label": "Close out an epic", "description": "Finish remaining stories in an epic / Hoàn thành các story còn lại của một epic"}, {"label": "Mixed — I'll describe the goal", "description": "Custom sprint goal / Mục tiêu sprint tùy chỉnh"}]}]}
+```
+
+---
+
+## Step 3 — Auto-select stories
+
+**Selection algorithm**:
+1. Start with stories that have unresolved blockers cleared first (dependencies already done).
+2. Pick P0 → P1 → P2 stories in order.
+3. Stop when total estimate reaches capacity threshold (95% capacity max — leave buffer).
+4. Flag stories that are too large (XL) and recommend splitting before including.
+
+**Display the sprint board**:
+
+```
+Sprint <N> — <start date> to <end date>
+Goal: <sprint goal>
+Capacity: <X> points / <Y> days
+
+SELECTED (<total points> / <capacity>):
+  ✓ <PREFIX>-STORY-001 <title>  [S]  2 pts  — Priority: P0
+  ✓ <PREFIX>-STORY-002 <title>  [M]  4 pts  — Priority: P0
+  ✓ <PREFIX>-STORY-005 <title>  [M]  4 pts  — Priority: P1
+  ✓ <PREFIX>-STORY-007 <title>  [S]  2 pts  — Priority: P1
+  ...
+  Total: XX pts / <capacity> pts
+
+NOT SELECTED (cut for capacity or dependency):
+  ✗ <PREFIX>-STORY-008 <title>  [L]  8 pts  — Cut: over capacity
+  ✗ <PREFIX>-STORY-003 <title>  [M]  4 pts  — Cut: blocked by STORY-002
+  ...
+
+BLOCKERS / RISKS:
+  ⚠ STORY-006 depends on STORY-004 (in-progress) — not yet done
+```
+
+---
+
+## Step 4 — PO adjustment
+
+Use AskUserQuestion to let PO adjust the selection:
+
+```json
+{"questions": [{"question": "Sprint board looks good?\n(Tiếng Việt: Bảng sprint trông ổn không?)", "header": "Adjust sprint", "multiSelect": false, "options": [{"label": "Looks good — save the sprint plan", "description": "Write the file / Lưu kế hoạch sprint"}, {"label": "Swap a story out", "description": "Remove one and add another / Thay một story"}, {"label": "Add a story (I'll accept the overcommit risk)", "description": "Force-add a story beyond capacity / Thêm story dù vượt năng lực"}, {"label": "Remove a story", "description": "Take one off the board / Bỏ một story khỏi danh sách"}]}]}
+```
+
+---
+
+## Step 5 — Write sprint plan file
+
+```markdown
+---
+title: Sprint <N> Plan
+sprint: <N>
+start: <YYYY-MM-DD>
+end: <YYYY-MM-DD>
+goal: <sprint goal>
+capacity: <X> points
+committed: <Y> points
+team: <from config>
+created: <YYYY-MM-DD>
+po: <from config>
+---
+
+# Sprint <N>: <slug>
+
+## Goal
+<Sprint goal statement>
+
+## Sprint Board
+
+### Selected (<Y>/<X> pts)
+| Story | Title | Size | Pts | Epic | Priority |
+|-------|-------|------|-----|------|----------|
+| ... | ... | S | 2 | EPIC-01 | P0 |
+
+### Not Selected
+| Story | Title | Reason |
+|-------|-------|--------|
+| ... | ... | Over capacity / Blocked by ... |
+
+## Blockers & Dependencies
+- <List any known blockers entering the sprint>
+
+## Notes
+<Any team notes, leave days, or known risks>
+```
+
+Save path:
+- Silver Tiger: `research/SPRINT-{N}-{slug}-{date}.md`
+- Standalone: `.compass/Research/SPRINT-{N}-{slug}-{date}.md`
+
+```bash
+compass-cli index add "<output-file-path>" "research" 2>/dev/null || true
+```
+
+## Save session
+
+`$PROJECT_ROOT/.compass/.state/sessions/<timestamp>-sprint-<N>/transcript.md`
+
+## Edge cases
+
+- **No backlog score file found**: rank by priority from frontmatter only; note in plan that scoring was not available.
+- **All stories are XL**: stop and recommend splitting each with `/compass:story` before planning.
+- **Capacity is zero or not provided**: refuse to generate a plan — ask again with a concrete number.
+- **Stories have no estimates**: use T-shirt size heuristic (XS=1, S=2, M=4, L=8, XL=13) and mark as "estimated, not confirmed".
+- **Sprint number conflict** (file already exists for SPRINT-N): increment to SPRINT-N+1, warn the user.
+- **PO force-adds stories beyond capacity**: include them but add a prominent `⚠️ OVERCOMMIT: +X pts over capacity` warning in the file header.
+- **Dependencies are circular**: flag immediately, do not include either story until the cycle is resolved.

package/core/workflows/status.md

@@ -0,0 +1,185 @@
+# Workflow: compass:status
+
+You are the project dashboard. Mission: show a complete overview of all documents, epics, stories, and their statuses.
+
+**Principles:** One glance — everything visible. Color-code by status. Show progress percentages. Highlight blockers. No file is saved — display only. Fast: under 10 seconds.
+
+**Purpose**: Instant project health check — count and status of every artifact type, progress bars, blockers, and recent activity. Like `git status` for your product workspace.
+
+**Output**: Printed to terminal only. No file created.
+
+**When to use**:
+- Morning standup — quick pulse check
+- Before a planning session — see what's done vs in-flight
+- After a series of commands — verify everything landed correctly
+
+---
+
+Apply the UX rules from `core/shared/ux-rules.md`.
+
+---
+
+## Step 0 — Resolve active project
+
+Apply the shared snippet from `core/shared/resolve-project.md`. It sets up `$PROJECT_ROOT`, `$CONFIG`, and `$PROJECT_NAME` for downstream steps and prints the "Using: <name>" banner.
+
+From `$CONFIG`, extract the required fields:
+- `lang`, `mode`, `prefix`, `project_name` (or derive from folder name)
+
+**Error handling**:
+- If `config.json` missing → print: "No Compass project found in this directory. Run `/compass:init` to set one up." Stop.
+- If corrupt → print: "Config file appears corrupt. Run `/compass:init` to repair it." Stop.
+- If valid but `mode` missing → default to standalone, continue.
+
+**Language enforcement**: ALL output in `lang`. No file created — language applies to terminal output only.
+
+---
+
+## Step 1 — Load index
+
+Run:
+```bash
+compass-cli index list 2>/dev/null
+```
+
+If the index is empty or the command fails → fall back to direct glob scanning (Steps 2–3).
+
+---
+
+## Step 2 — Count all document types
+
+Scan and count by type. For each file, read its frontmatter `status` field.
+
+**PRDs** — glob `prd/*.md` (Silver Tiger) or `.compass/PRDs/*.md` (standalone):
+- Count by status: `draft`, `review`, `approved`, `archived`
+
+**Epics** — glob `epics/{prefix}-EPIC-*/epic.md` (Silver Tiger):
+- Count by status: `planned`, `active`, `completed`, `on-hold`
+
+**Stories** — glob `epics/*/user-stories/*.md` (Silver Tiger) or `.compass/Stories/*.md` (standalone):
+- Count by status: `pending`, `in-progress`, `done`, `blocked`
+
+**Research** — glob `research/*.md` or `.compass/Research/*.md`:
+- Count all files (no status breakdown needed)
+
+**Ideas** — glob `research/IDEA-*.md` or `.compass/Ideas/*.md`:
+- Count all files
+
+**Backlog** — glob `research/BACKLOG-*.md` or `.compass/Backlog/*.md`:
+- Count all files
+
+**Technical** — glob `research/TECH-*.md` or any file with `type: technical` in frontmatter:
+- Count all files
+
+**Release notes** — glob `release-notes/*.md`:
+- Find the most recent file (by date in filename)
+
+---
+
+## Step 3 — Detect blockers and recent activity
+
+**Blockers**: scan stories with `status: blocked` — read their `depends-on` frontmatter field. Build a list: `STORY-XXX depends on STORY-YYY (status: in-progress/pending)`.
+
+**Recent activity**: find the 5 most recently modified artifact files. Extract: filename, type, status, modification date. Sort by recency.
+
+**Progress calculation**:
+- Stories progress = `done / (done + in-progress + pending + blocked)` × 100%
+- Epic progress = `completed / total epics` × 100%
+
+**Progress bar**: build a 10-block bar.
+```
+████████░░ 80%   →  8 filled blocks
+████░░░░░░ 40%   →  4 filled blocks
+░░░░░░░░░░  0%   →  0 filled blocks
+```
+
+---
+
+## Step 4 — Display dashboard
+
+Print the dashboard. Adapt language to `lang`. Example (en):
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  COMPASS — Project Status
+  Project: <name> | Mode: <mode> | Prefix: <PREFIX>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Documents:
+    PRDs:         <N>  (<X> draft, <Y> review, <Z> approved)
+    Epics:        <N>  (<X> active, <Y> planned, <Z> completed)
+    Stories:      <N>  (<X> done, <Y> in-progress, <Z> pending, <W> blocked)
+    Research:     <N>
+    Ideas:        <N>
+    Backlog:      <N>
+    Technical:    <N>
+    Release notes: <N>  (latest: v<version> on <date>)
+
+  Progress:
+    Stories:   <bar> <X>% done (<done> / <total>)
+    Epics:     <bar> <X>% closed (<closed> / <total>)
+
+  Blockers:
+    <emoji> <PREFIX>-STORY-<N> — <title>
+        depends on <PREFIX>-STORY-<M> (status: <status>)
+    <none if no blockers>
+
+  Recent activity:
+    <date>:      <type> <filename> (<status>)
+    <date>:      <type> <filename> (<status>)
+    ... (up to 5 entries)
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  Next suggested actions:
+    <If 0 epics>       /compass:epic     — create your first epic
+    <If 0 stories>     /compass:story    — write stories for an epic
+    <If stories done>  /compass:release  — generate release notes
+    <If blockers>      Resolve blockers before sprint planning
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+Vietnamese version (used when `lang=vi`):
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  COMPASS — Trạng thái Dự án
+  Dự án: <name> | Chế độ: <mode> | Prefix: <PREFIX>
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Tài liệu:
+    PRDs:         <N>  (<X> nháp, <Y> đang review, <Z> đã duyệt)
+    Epics:        <N>  (<X> đang chạy, <Y> đã lên kế hoạch, <Z> hoàn thành)
+    Stories:      <N>  (<X> xong, <Y> đang làm, <Z> chờ, <W> bị chặn)
+    Nghiên cứu:   <N>
+    Ý tưởng:      <N>
+    Backlog:      <N>
+    Kỹ thuật:     <N>
+    Release notes: <N>  (mới nhất: v<version> ngày <date>)
+
+  Tiến độ:
+    Stories:   <bar> <X>% hoàn thành (<done> / <total>)
+    Epics:     <bar> <X>% đóng (<closed> / <total>)
+
+  Vấn đề chặn:
+    <PREFIX>-STORY-<N> — <title>
+        phụ thuộc vào <PREFIX>-STORY-<M> (trạng thái: <status>)
+
+  Hoạt động gần đây:
+    <date>:  <type> <filename> (<status>)
+    ...
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+```
+
+**Do not use AskUserQuestion** — this is a display-only command. Print and stop.
+
+---
+
+## Edge cases
+
+- **Project is brand new (0 files)**: print a welcome message instead of an empty dashboard — "No documents yet. Start with `/compass:prd` or `/compass:brief` to create your first artifact."
+- **Index is stale** (index exists but files were added manually): fall back to glob scan, add a note: "(Index may be stale — run `compass-cli index rebuild` to refresh)"
+- **Status frontmatter missing from a file**: count it as "unknown" in its category.
+- **Standalone mode with no `compass/` folder**: print: "No compass/ folder found. Run `/compass:init` to initialize a standalone project."
+- **Very large project (>100 stories)**: cap recent activity to 5 entries; show totals only for counts above 50 (e.g. "Stories: 120 (45 done, 62 in-progress, 13 pending)").
+- **All stories are done and no blockers**: celebrate — print a "All clear" banner: "All stories complete — ready for `/compass:release`."
+- **$ARGUMENTS provided** (e.g. `/compass:status epic-03`): filter the dashboard to show only artifacts related to that epic or keyword.