> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guardway.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> Tracks engineering work in Linear for team visibility on Guardway AI (GUA). Use when starting or continuing any substantive task: bugfix, feature, refactor, chore, release, investigation, or implementation. Trigger on "implement", "fix", "add", "refactor", "GUA-", "Linear", "ticket", or when assigned coding work without an existing issue reference.


# SKILL

# Linear issue tracking (Guardway AI)

Every substantive engineering task must have a Linear issue so the team has
visibility into in-flight work. Do not begin implementation until a GUA issue
exists or is confirmed.

## Workflow

### 1. Find or create (start of work)

* User gave `GUA-123` (or `GUA-123` in chat)? → update that issue; do not create a duplicate.
* Else search: `list_issues` with `team: "Guardway AI"`, `project: "<default project>"`, `query: "<keywords from task>"`.
* Reuse an open issue when scope matches; otherwise `save_issue` to create.

### 2. Set active

On create or reuse:

* `state`: `In Progress`
* `assignee`: `me` when acting for the current user
* `project`: default for this repo (see Repo defaults)
* `team`: `Guardway AI` (required on create)
* `description`: use template below

### 3. Implement and comment

Post milestone updates with `save_comment` (`issueId: "GUA-123"`, markdown body):
approach, blockers, key files touched. Do not spam — comment at meaningful checkpoints.

### 4. PR and completion

* PR opened → `save_issue` with `state: "In Review"` and `links: [{url, title}]` for the PR.
* Work complete (merged or no PR) → `state: "Done"` plus a final comment summarizing what shipped.

**Status flow:** `Todo` → `In Progress` → `In Review` (PR open) → `Done`.

## Linear MCP tools

Use the `plugin-linear-linear` MCP server:

| Step     | Tool           | Key fields                                                                       |
| -------- | -------------- | -------------------------------------------------------------------------------- |
| Search   | `list_issues`  | `team`, `project`, `query`                                                       |
| Create   | `save_issue`   | `title`, `team: "Guardway AI"`, `project`, `state: "In Progress"`, `description` |
| Update   | `save_issue`   | `id: "GUA-123"`, `state`, `links`, `labels`, `relatedTo`                         |
| Progress | `save_comment` | `issueId: "GUA-123"`, `body` (markdown)                                          |

Team invariant: always **Guardway AI** (key **GUA**).

## Issue title format

```
[type(scope)]: short description
```

Examples: `fix(dashboard): audit page empty state`, `feat(gateway): MCP proxy timeout`.

## Issue description template

```markdown theme={null}
## Context / Why
[Problem or request]

## Proposed change
[What will change — paths, behavior]

## Acceptance criteria
- [ ] …

## Repo
`<repo-name>` (`<path>`)

## Related
PRs, cross-repo issues, Slack threads
```

## Agent obligations

1. **Before coding:** confirm a GUA issue exists; create one if not.
2. **Cross-repo work:** add label `cross-repo`; link related issues via `relatedTo`.
3. **On PR:** link the PR and move to `In Review`.
4. **On completion:** move to `Done` with a summary comment.
5. **Do not skip** Linear for small fixes, agent-only sessions, or docs-only edits unless the user explicitly says to skip tracking.

## Repo defaults

* **Repo:** guardway-docs
* **Path:** `guardway-docs/`
* **Default Linear project:** Docs and Developer Enablement