AI Workflows

Reusable AI coding workflows and focused skills a team member can install globally or per-project, in any environment: Cursor, Claude Code, and others.

What's Included

Skills

• gh-stack -- Manages stacked PRs and splits multi-part work into reviewable branches with gh stack. Covers creation, viewing, editing, push, submit, sync, rebase, merge, and checkout. See skills/gh-stack/SKILL.md.

• Report Bug -- Drafts an evidence-based Jira Bug, supports consumer-owned project templates and field vocabulary with an EDM-style fallback, distinguishes Severity from triage-owned Priority, checks duplicate/regression context, supports explicitly reviewed optional attachments, works through Jira MCP, CLI, or REST capabilities, and creates the issue only after confirmation. See skills/report-bug/SKILL.md.

Workflows

• Bugfix -- Systematic bug resolution: assess the report, reproduce, diagnose root cause, fix, test, review, document, and submit a PR. Supports iterative PR feedback and an unattended mode. Used in the Flight Control projects (flightctl, flightctl-ui). See bugfix/README.md.

• Docs Writer -- Systematic documentation creation: gather context, plan structure, draft content, validate, apply changes, create merge request. Used in the edge-manager downstream docs project. See docs-writer/README.md.

• Triage -- Bulk Jira bug triage with AI-driven categorization and interactive HTML reports. See triage/README.md.

• PRD -- Requirements-to-PRD workflow: ingest requirements from Jira, clarify ambiguities through iterative Q&A, draft a Product Requirements Document, revise based on feedback, publish as a GitHub PR, and respond to reviewer comments. See prd/README.md and the PRD Guide.

• Design -- Design-and-decompose workflow: ingest a PRD, draft a technical design document, decompose into Jira-ready epics and stories, revise based on feedback, publish as a GitHub PR, respond to reviewer comments, and sync epics/stories to Jira. See design/README.md.

• UI Design -- UI design workflow for [UI] stories: ingest an optional UX handoff and design document, decompose into component architecture with hook design, state management, route structure, and data flow mapping, review the API surface for gaps, publish as a GitHub PR, and sync [DEV] stories for backend work to Jira. See ui-design/README.md.

• Implement -- Story-to-code workflow: take a Jira Story, plan the implementation, write contract-based tests and production code via TDD, validate against the project's CI expectations, and manage review via GitHub PRs. See implement/README.md.

• UI Implement -- Story-to-code workflow for UI/front-end [UI] stories: take a Jira Story, discover the project's UI toolchain (test framework, design system, i18n), plan the implementation with component/hook interfaces, write contract-based unit tests and production code via TDD, write integration/e2e test stubs, validate against the project's CI expectations, and manage review via GitHub PRs. See ui-implement/README.md.

• E2E -- Story-to-tests workflow for [QE] stories: discover the project's e2e testing infrastructure, map acceptance criteria to test scenarios, write e2e test code following the project's patterns and reference suite, validate against anti-patterns and scenario coverage, and manage review via GitHub PRs. See e2e/README.md.

• Code Review -- AI-driven code review for uncommitted changes: discover project conventions, review with an independent reviewer perspective, present findings with honest implementor assessments for human decision, iterate until approved. Supports unattended mode for fully automated review-fix-iterate cycles. See code-review/README.md.

• CVE Fix -- Automated CVE remediation: read vulnerability details from Jira, apply multi-strategy dependency fixes, validate, create pull requests, backport to release branches, and close Jira tickets. Language-agnostic. See cve-fix/README.md.

• AI-Ready -- Scans a codebase and creates or updates AGENTS.md with project-specific build commands, test patterns, and coding standards. See ai-ready/README.md.

• KCS -- KCS Solution article workflow: gather bug context from Jira, draft a KCS article in markdown, validate against the KCS Content Standard, and produce a handoff message for the support engineer. See kcs/README.md.

• Rebase Stack -- Rebase a stacked-branch chain onto an updated base using gh stack, guide through conflict resolution, validate each branch, and push all updated branches. See rebase-stack/README.md.

• Sizing -- Pre-cycle Feature sizing: ingest Features from Jira (single or batch by Fix Version), assess against a T-shirt size rubric (XS–XXL) with per-team effort breakdowns (DEV, QE, UX, UI, DOCS), and write results back to Jira. See sizing/README.md.

• Skill Reviewer -- Meta-workflow that audits AI skill directories against eight quality dimensions. See skill-reviewer/README.md.

• UX Design -- UX design workflow: ingest a feature request, conduct user research, generate prototypes, run heuristic evaluation, and produce a validated design handoff for the ui-design workflow. See ux-design/README.md.

How It Works

Each workflow is a top-level directory with a SKILL.md, while focused skills live under skills/<name>/. Both use plain markdown with no IDE-specific syntax. Workflows may add phase skills and commands; simple skills use only the supporting references or scripts they need. The installer discovers both forms.

~/.ai-workflows/  (symlink to your clone)
  bugfix/
    SKILL.md, skills/, commands/
  docs-writer/
    SKILL.md, skills/, commands/
  skills/
    gh-stack/
      SKILL.md, references/
    report-bug/
      SKILL.md, references/

git pull updates everything instantly through the symlink.

Configuring Report Bug

report-bug derives its Jira target from the request, applicable project AGENTS.md, issue context, or the consuming repository. Teams can commit .workflows/report-bug/config.yaml and an optional Markdown template:

jira_url: https://example.atlassian.net
project: TEAM
issue_type: Bug
template: template.md
severity_field: Severity
severity_mapping:
  critical: Critical
  high: High
  medium: Medium
  low: Low
  informational: Informational
environment_field: Environment
parent_field: Parent
affects_version_field: Affects versions
provenance:
  enabled: true
  agent: null
  model: null

Without consumer configuration, the skill prompts for unresolved target details and offers the EDM project and EDM-style template as an opinionated fallback; it never selects that target silently. Priority is always left unset for triage. Parent relationships are validated, Affects Version requires confirmation, and assignee is set only when requested; Fix Version and Target Version remain planning decisions. The skill is attended by design: creating a bug, adding evidence to a matching issue, and uploading attachments each require an explicit preview and approval. Generated descriptions identify the skill and version. Agent/model identity is included only when the runtime exposes it authoritatively or configuration names it explicitly.

Installation

Clone the repo and run the install script:

git clone https://github.com/flightctl/ai-workflows.git
cd ai-workflows

Cursor

User-level -- available in all your projects:

./install.sh cursor

Project-level -- shared with anyone who clones the repo:

./install.sh cursor --project /path/to/project

Claude Code

User-level:

./install.sh claude

Project-level:

./install.sh claude --project /path/to/project

Codex

User-level:

./install.sh codex

Project-level:

./install.sh codex --project /path/to/project

All Environments at Once

./install.sh all                          # user-level
./install.sh all --project /path/to/proj  # project-level

Selective Installation

Each workflow or skill is intended for a specific project or use case:

• bugfix -- the Flight Control projects (flightctl, flightctl-ui)
• code-review -- any project; reviews uncommitted changes against discovered project conventions
• docs-writer -- the edge-manager downstream docs project
• prd -- teams drafting Product Requirements Documents from Jira features
• design -- teams creating technical design documents and Jira-ready epic/story breakdowns from PRDs
• ui-design -- teams creating UI design documents (component architecture, hooks, state, routes, data flow) for [UI] stories
• implement -- teams implementing Jira stories produced by the design workflow
• ui-implement -- teams implementing [UI] stories for front-end/React projects produced by the design workflow with a ui-design document
• e2e -- teams writing e2e tests for [QE] stories produced by the design workflow
• cve-fix -- teams patching CVEs and updating vulnerable dependencies from Jira vulnerability tickets
• ai-ready -- onboarding any project for AI agents by generating AGENTS.md
• kcs -- teams writing KCS Solution articles for known issues with workarounds
• triage -- teams that want bulk Jira triage, categorization, and HTML reports from this repo or a clone
• sizing -- teams sizing Features for cycle planning using T-shirt sizes with per-team effort breakdowns
• skill-reviewer -- reviewing or standardizing Cursor/agent skills and skill packs (structure, clarity, completeness)
• gh-stack -- managing stacked PRs with gh stack in any project using stacked branches
• report-bug -- filing complete Jira bugs with consumer-configurable targets and templates while leaving Priority for triage

Use --packages to install only the named workflows or skills:

./install.sh cursor --project ~/flightctl --packages bugfix
./install.sh cursor --project ~/edge-manager --packages docs-writer
./install.sh cursor --packages report-bug
./install.sh --list                       # show available workflows and skills

The former --workflows selector remains available as a deprecated alias.

For project-level Cursor installs, add the generated commands directory to .gitignore:

.cursor/commands/

The skill symlinks under .cursor/skills/ and .agents/skills/ may also need ignoring depending on your project's conventions.

Scopes

Scope	Cursor	Claude Code	Gemini	Codex
User (default)	~/.cursor/skills/<package> + ~/.cursor/commands/	~/.claude/CLAUDE.md	~/.gemini/skills/<package>	~/.agents/skills/<package>
Project (--project)	.cursor/skills/<package> + .cursor/commands/	.claude/CLAUDE.md	.gemini/skills/<package>	.agents/skills/<package>

Usage

Claude Code

Invoke a workflow command using the colon-namespaced format:

• /bugfix:assess, /bugfix:diagnose, /bugfix:fix, ...
• /code-review:start, /code-review:continue, /code-review:clean
• /docs-writer:gather, /docs-writer:plan, /docs-writer:draft, ...

Cursor

The installer generates flat command files in .cursor/commands/ so each phase appears in the Cursor slash menu:

• /bugfix-assess, /bugfix-diagnose, /bugfix-fix, ...
• /code-review-start, /code-review-continue, /code-review-clean
• /docs-writer-gather, /docs-writer-plan, /docs-writer-draft, ...

Cursor scans both project-level (.cursor/commands/) and user-level (~/.cursor/commands/) directories. Commands are plain .md files — no manifest or wrapper directories needed. They are created by install.sh and cleaned up by uninstall.sh.

Codex

Invoke a package as a skill and pass the workflow phase as context:

• $bugfix assess EDM-123
• $design ingest PRD-123
• $report-bug

Codex discovers user-level and repository-level skill symlinks automatically; see Where Codex loads local skills.

Updating

cd ~/.ai-workflows && git pull
# or, if you enabled the update notifier:
aiw-update

Optional: daily update notifier (Linux)

On Linux desktops with systemd user sessions and notify-send, install.sh can prompt to enable a daily check. If ~/.ai-workflows is behind origin/main, you get a desktop notification suggesting aiw-update.

./install.sh cursor                  # prompts [y/N] when supported
./install.sh cursor --with-update-timer
./install.sh cursor --no-update-timer
./hack/install-update-timer.sh       # enable later
./hack/install-update-timer.sh --remove

Uninstalling

./uninstall.sh                                          # user-level everything
./uninstall.sh cursor                                   # user-level Cursor only
./uninstall.sh codex                                    # user-level Codex only
./uninstall.sh cursor --packages bugfix                 # remove specific package
./uninstall.sh cursor --project /path/to/proj           # project-level Cursor
./uninstall.sh all --project /path/to/proj              # project-level everything

Contributing

See CONTRIBUTING.md for how to add or modify workflows.

License

See LICENSE.