Harness
Safina is the team’s engineering culture layer — the shared home for standards, MCP access, and the workflow commands that connect daily developer work to Linear, GitHub, and Slack. It is not a backlog. It is not a wiki of feature state. It is the protocol and tooling that makes the team run consistently, whether they’re using Claude on the CLI, VS Code, the desktop app, or iOS.
The backlog moved to Linear (Tier 1: Taha and Adnan) and GitHub issues (Tier 2: everyone else, bidirectionally synced with Linear).
Three planes
The harness is composed, not built. The primitives already exist — we wire them together.
| Plane | Role | What it provides |
|---|---|---|
| Linear / GitHub Issues | Backlog | Work items, ticket IDs, status, assignees. Linear is the canonical source; GitHub issues sync for Tier 2 developers. |
| Safina (this repo) | Standards + commands | Skills docs, MCP access map, shared workflow commands, commit convention, PR template. |
| Claude Code | Execution runtime | Where commands run — locally on the developer’s machine, in any Claude surface. |
| GitHub | Work + audit trail | PRs, issue threads, commit history. Downstream output of workflow execution. |
| Slack | Communication | Standups, QA handoffs, PR notifications. Driven by Claude via the developer’s connected Slack account. |
There is no central orchestrator and no message bus to operate.
How work flows
Four commands handle the developer loop. They sit alongside Claude’s built-in commands (not replacing them).
/ilmiya:backlog → (work, commits) → /ilmiya:test → /ilmiya:hunt → /ilmiya:update
Every session:
/ilmiya:backlog— Pull assigned tickets (Linear or GitHub), pick today’s focus, create or update issues./ilmiya:test(before merging) — Conformance and correctness check against Ilmiya’s skills docs: API design, naming, error design, observability, test coverage, QA readiness, commit convention. Severity-graded findings:Errors/Patches/Notices. Does not modify code./ilmiya:hunt(before merging or any time) — Offensive analysis: security vulnerabilities, dependency CVEs, logic bugs, regressions, flaky tests, data integrity gaps, resource leaks, multi-tenancy risks. Looks for problems that engineers wouldn’t catch in normal review. Does not modify code./ilmiya:update(after committing work) — Reads recent git commits, links them to the right issue, posts a smart summary comment on that issue, and notifies Slack. If commits don’t follow the Ilmiya convention, flags them as advisory. Git workflow (commits, pushes, PRs) is the developer’s own responsibility — these commands manage the backlog and communication layer only.
How to install
One-time setup per developer:
git clone git@github.com:ilmiya/safina.git
cd safina
./install.sh
The script copies .claude/commands/*.md to ~/.claude/commands/ and creates ~/.claude/ilmiya-config.json with your name, GitHub handle, Linear access flag, and default Slack channel. Commands are then available in any Claude Code surface.
To update when new commands ship: git pull && ./install.sh
Connectivity
Commands use the MCP connectors in the developer’s Claude account — no API keys to manage:
| Connector | Used by | Required for |
|---|---|---|
| Linear MCP | Tier 1 (Taha, Adnan) | /ilmiya:backlog and /ilmiya:update ticket operations |
GitHub MCP or gh CLI | All developers | Tier 2 ticket access; /ilmiya:test and /ilmiya:hunt can log findings to issues |
| Slack MCP | All developers | /ilmiya:update Slack notifications and QA handoffs |
If a connector is missing, commands prompt: “Connect [service] at claude.ai/settings.”
Developer tiers
| Tier | Who | Ticket source |
|---|---|---|
| Tier 1 | Taha, Adnan | Linear — mcp__claude_ai_Linear__* tools |
| Tier 2 | All other developers | GitHub issues in ilmiya/safina — gh CLI or GitHub MCP |
The bidirectional sync between Linear and GitHub means Taha always sees Tier 2 work in Linear. Tier 2 developers never need Linear access.
The engineering culture layer
skills/ and mcp/ are the parts of Safina that agents and developers read for context — not execution state. They are the “why” and “how” behind the work:
skills/— Standards, patterns, best practices for building at Ilmiya. Commands read the relevant skill before acting (e.g.,/qareadsskills/qa.mdbefore posting a handoff comment).mcp/— Which MCP server to use for which live system query, and how to connect to it.
These don’t decay like feature files did. They’re the stable foundation.
What changed from the old model
| Old model | New model |
|---|---|
| Safina tracked feature state (V-FIB files) | Linear tracks feature state |
priorities.md was the team’s backlog | Linear is the backlog |
updates/ captured daily contributor logs | Ticket comments + Slack own daily updates |
/plan, /ship, /reflect were the SDLC (overriding Claude’s built-ins) | /ilmiya:backlog + /ilmiya:update sit alongside Claude’s commands |
| Safina was read first for product context | Linear/GitHub issues are read first for product context; Safina is read for standards |
- Skills · MCP · AGENTS.md · Back to index