Helix — AI QA assistant

Version: 1.5.31 · Releases

Portable skill pack for AI agents: FE/API manual test-case prep (with coverage + quality review), Playwright ticket testing, create bug, and Jira bug retests — one entry menu across tools.

Scope & expectations Helix is built for QA work with clear boundaries—a defined ticket, environment, inputs, and what “done” looks like. When the scope is vague or still in flux, you may need extra clarification rounds, and the output may require more review. Sharper scope upfront usually means stronger, faster results.

Why Helix

TC prep workflows include AC/EC or spec/Swagger alignment review, ISTQB / ISO/IEC/IEEE 29119-3–aligned quality checks, and mandatory Jira post-publish review before close-out (see qa-evidence-gates.md). FE prep also ends with a four-axis final TC review report (AC/EC alignment, spelling, numbering, scope).

Delivery formats (TC prep): CSV/Excel (default for spreadsheets), Jira comment + attachment, and optionally Test.md — an agent-native format for Kane CLI / Playwright agents (test-md-format.md). Test.md is additive; never replaces CSV for spreadsheet users.

Supported AI agents

Helix uses the open [Agent Skills](https://agentskills.io) format (SKILL.md). One install links skills for every path your machine supports.

Team / repo scope (optional): .github/skills/, .agents/skills/, .windsurf/skills/, .cline/skills/, .gemini/skills/ when you run workspace linking (below).

Details: docs/supported-agents.md · copy-paste prompts: references/agent-entry.md

Web-only chat without skill discovery is not supported — use an agent that loads SKILL.md folders.

Install (one-time)

Step 1 — Everyone (same command)

curl -sL https://raw.githubusercontent.com/Thitic9203/helix/main/scripts/install.sh | bash

This clones Helix to ~/.helix/tc-fe-prep, symlinks helix + 5 workflow skills into the global folders above (skips paths that do not exist on your OS yet), registers the Claude Code plugin cache, enables `helix@helix` (and disables legacy helix@local), and wires SessionStart hooks for bootstrap + auto-update.

Step 2 — By agent (what you do next)

Workspace link (one line, from your project root):

HELIX_LINK_WORKSPACE=$PWD ~/.helix/tc-fe-prep/scripts/link-skills.sh

Commit .github/skills/ if your team uses Copilot on the same repository. The Helix repo ships portable relative symlinks under .github/skills/ (safe to commit).

Health check (helix doctor)

After install (or when skills do not appear):

bash ~/.helix/tc-fe-prep/scripts/helix-doctor.sh
# optional: also check project skill folders
HELIX_LINK_WORKSPACE=$PWD bash ~/.helix/tc-fe-prep/scripts/helix-doctor.sh

Reports Helix version, global skill symlinks per agent, and Claude plugin cache. Works best with: Jira (MCP or logged-in browser), Playwright in your app repo, optional references/*-guide.md in your project.

Usage

You do not have to start with `/helix`. If you already know the workflow, call it directly — that skips the menu and is the recommended path. Use /helix (or skill `helix`) only when you want the menu or are unsure which workflow fits.

Run a workflow directly (recommended when you know the goal)

Append a Jira key or URL when your tool supports it, e.g. /tc-fe-prep PROJ-123 or “run retest-bug-workflow on PROJ-456”.

Full map: references/skill-routing.md · copy-paste prompts: references/agent-entry.md

Open the Helix menu (optional — when unsure)

The menu offers options 1–6 (TC FE, TC API, retest, testing ticket, create bug, other) and routes to the same workflows as the table above.

First run tips

• Workflows auto-load *`references/-guide.md`** in your repo when present (workspace-guide-discovery.md) — fewer repeated questions.
• Long sessions may write `references/helix-handoff-{KEY}.md` so you can resume in a new chat (session-closing.md).
• Menus and questions are English only — references/user-communication.md. Jira/Sheet content may follow your project language after you approve.
• Non–Claude Code agents: read AGENTS.md if the tool loads repo-level agent instructions.

Update (when a new version ships)

Releases: github.com/Thitic9203/helix/releases (tagged on every main push that bumps VERSION).

Default: auto-update (recommended)

After a one-time install, you usually do not run git pull yourself. When we publish a new version on main, your machine catches up on the next agent session (throttled to at most once every 4 hours):

Auto-update steps (when `VERSION` on GitHub is newer):

1. git pull --ff-only in ~/.helix/tc-fe-prep (skill symlinks pick up new SKILL.md immediately)
2. link-skills.sh (refresh global + optional workspace symlinks)
3. claude plugin update helix@helix (Claude Code marketplace plugin + hooks)

Log file: ~/.helix/auto-update.log · Doctor: helix-doctor.sh

# Manual check (same as the hook, useful for debugging)
HELIX_FORCE_UPDATE=1 HELIX_AUTO_UPDATE_VERBOSE=1 bash ~/.helix/tc-fe-prep/scripts/helix-auto-update.sh

Notes

• Needs network when the session starts; offline → skip (no error).
• Cursor / Copilot / Codex / … — skills update via symlinks after pull; Reload window (Cursor) if the agent still shows old skill text.
• Claude Code — after a plugin version jump, start a new session once if /helix or slash commands look stale (skills via ~/.claude/skills are usually current sooner).

Claude Code plugin id

install.sh and claude-plugin-sync.sh keep the marketplace plugin aligned with VERSION.

Manual update (fallback)

Use if auto-update is off, you deleted ~/.helix/tc-fe-prep, or you want to force sync now:

cd ~/.helix/tc-fe-prep && git pull
bash ~/.helix/tc-fe-prep/scripts/claude-plugin-sync.sh   # Claude Code: helix@helix
bash ~/.helix/tc-fe-prep/scripts/link-skills.sh            # if symlinks missing

Or re-run the full installer:

curl -sL https://raw.githubusercontent.com/Thitic9203/helix/main/scripts/install.sh | bash

By agent (when something still looks old)

Marketplace-only install (no ~/.helix clone)

If you only installed `helix@helix` from Claude marketplace (never ran curl …/install.sh):

• Plugin + hooks can still update via SessionStart → claude-plugin-sync.sh
• Global skills (~/.cursor/skills, etc.) need `install.sh` once so symlinks point at ~/.helix/tc-fe-prep

Current release: README version line above or Releases.

<details> <summary>Manual install (contributors)</summary>

git clone https://github.com/Thitic9203/helix.git
cd helix
./scripts/setup.sh
git config core.hooksPath scripts/hooks

Fewer agent questions while developing Helix (optional). Opening the repo in Claude Code already gives you read-only command allows + context hooks (committed .claude/settings.json). For the fuller global config (acceptEdits, wider safe allowlist, "bias toward action" rules in ~/.claude/CLAUDE.md):

bash scripts/helix-setup-devenv.sh             # opt-in, idempotent, backs up first
bash scripts/helix-setup-devenv.sh --uninstall # revert (keeps your own rules)

Idempotent and re-synced by auto-update once opted in. Requires jq. Details: docs/CONTRIBUTING.md.

</details>

Skills

Skill layout: Thin SKILL.md stubs (linked into ~/.cursor/skills/, etc.) point to full procedures in skills/deprecated/*/WORKFLOW.md. Claude Code also exposes /helix, /tc-fe-prep, … via commands/.

Prerequisites (human)

• Jira access to the issues you name
• Browser logged into Jira when posting large comments or UI retests
• Optional workspace guides: references/*-tc-fe-prep-guide.md, *-retest-guide.md, *-testing-ticket-guide.md

Docs

Scripts

Contributor: bump-version.sh, sync-version.sh --check, list-skills.sh, helix-regression-check.sh (pre-merge gate via /helix-check), helix-setup-devenv.sh (opt-in: fewer agent questions)

License

MIT — LICENSE