cristoslc Status
Cross-cutting project status dashboard. Aggregates data from artifact lifecycle (specgraph), task tracking (tk), git, GitHub issues, and session state into an activity-oriented view.
When invoked
Locate and run the status script. The script path is relative to this skill's directory — resolve from the skill's install location:
# Find the script relative to this skill's directory
SKILL_DIR="$(find . .claude .agents -path '*/swain-status/scripts/swain-status.sh' -print -quit 2>/dev/null)"
bash "$SKILL_DIR" --refresh
If the path search fails, glob for **/swain-status/scripts/swain-status.sh.
Present the script output verbatim — it contains OSC 8 terminal hyperlinks for clickable file paths and GitHub URLs.
The script collects from five data sources:
- Artifacts — specgraph cache (epic progress, ready/blocked items, dependency info)
- Tasks — tk (in-progress, recently completed)
- Git — branch, working tree state, recent commits
- GitHub — open issues, issues assigned to the user
- Session — bookmarks and context from swain-session
Output structure
The output is ordered by actionability, not by data source. It synthesizes data into decision support — not just raw listings.
- Session bookmark — if one exists, show it first ("where you left off")
- Pipeline — branch, dirty state, last commit
- Active Epics — each epic with contextual progress (e.g., "3/7 specs resolved (4 remaining)" or "needs decomposition into specs"), child items annotated with next-step hints and descriptions
- Decisions Waiting on You — items requiring human judgment (spec approvals, spike verdicts, ADR decisions, triage), sorted by downstream impact. These are the developer's bottleneck.
- Implementation — items the agent can handle autonomously (approved specs, implementing tasks), sorted by impact. Only shown when implementation-ready items exist.
- Blocked — artifacts waiting on dependencies, with descriptions and "(actionable now)" annotations where the blocker is in the ready list
- Tasks — in-progress and recently completed tk tasks
- GitHub Issues — assigned issues first, then open issues, with clickable links
- Artifact counts — summary footer
Clickable links
The script emits OSC 8 hyperlinks that work in iTerm2 and other modern terminals:
- File paths →
file:///path/to/doc— opens in default application - GitHub issue URLs →
https://github.com/owner/repo/issues/N— opens in browser - Artifact IDs → linked to their source file on disk
Present the script output directly — do not reformat or strip escape sequences.
Compact mode (MOTD integration)
The script supports --compact for consumption by swain-stage's MOTD panel:
bash scripts/swain-status.sh --compact
This outputs 4-5 lines suitable for the MOTD box: branch, active epic progress, current task, ready count, assigned issue count.
Cache
The script writes a JSON cache to the Claude Code memory directory:
~/.claude/projects/<project-slug>/memory/status-cache.json
- TTL: 120 seconds (configurable via
status.cacheTTLin settings) - Force refresh:
--refreshflag bypasses TTL - JSON access:
--jsonflag outputs raw cache for programmatic use
The MOTD can read this cache cheaply between full refreshes.
Follow-up actions
After presenting status, suggest relevant next steps based on what the data shows:
| Condition | Suggestion |
|---|---|
| Actionable items exist | "Ready to pick one up? Tell me which artifact to work on." |
| Blocked items exist | "Want to look at what's blocking {ID}?" |
| GitHub issues assigned | "Want to triage your assigned issues?" |
| No active tasks | "No tasks in progress. Want to start one from the ready list?" |
| Session bookmark exists | "Want to pick up where you left off?" |
Offer one or two suggestions, not all of them.
Settings
Read from swain.settings.json (project) and ~/.config/swain/settings.json (user override).
| Key | Type | Default | Description |
|---|---|---|---|
status.cacheTTL |
number | 120 |
Cache time-to-live in seconds |
Session bookmark
After presenting the status output, update the session bookmark via swain-bookmark.sh:
BOOKMARK="$(find . .claude .agents -path '*/swain-session/scripts/swain-bookmark.sh' -print -quit 2>/dev/null)"
bash "$BOOKMARK" "Checked status — 2 specs awaiting review, EPIC-002 needs decomposition"
- Note format: "Checked status — {key highlight}"
- Pick the single most actionable highlight from the output (decisions waiting, blocked items, or epic progress)
Error handling
- If specgraph is unavailable: skip artifact section, show other data
- If tk is unavailable: skip task section
- If gh CLI is unavailable or no GitHub remote: skip issues section
- If session.json doesn't exist: skip bookmark
- Never fail hard — show whatever data is available