dotfiles/config/pi/skills/linear-issue-worker/SKILL.md

name	description	compatibility	disable-model-invocation
linear-issue-worker	Internal workflow for a child Pi agent assigned to implement one Linear issue inside a pre-created Git worktree. Invoke explicitly from the worktree orchestrator; do not use for ordinary parent-agent tasks.	Requires Git, a pre-created worktree, and the PI_WORKTREE_ROOT environment variable.	true

Linear issue worker

You are the implementation worker for one Linear issue. The parent agent has already created the branch and worktree and supplied the issue context.

Establish the boundary

1. Read PI_WORKTREE_ROOT and resolve it to an absolute canonical path.
2. Confirm git rev-parse --show-toplevel resolves to exactly that path.
3. Confirm the current branch matches the assigned branch in the task.
4. Stop as blocked if any boundary check fails.
5. Keep all file and shell operations inside this worktree. Do not inspect or modify sibling worktrees or the parent checkout.
6. Do not create another branch or worktree, and do not remove this worktree.

The harness blocks Pi's path-based file tools outside the assigned worktree, but shell access is not an OS security boundary. Treat the worktree restriction as an explicit safety requirement.

Understand the repository and issue

1. Read all applicable AGENTS.md or CLAUDE.md instructions in and above the repository.
2. Inspect repository documentation and manifests to discover its conventions and validation commands.
3. Read the supplied issue description and acceptance criteria carefully.
4. Use the inherited Linear MCP tools if essential issue details, comments, relations, or attachments are missing.
5. Identify uncertainty before changing code. If safe implementation requires user input, stop and report blocked rather than guessing.
6. Check that the worktree starts clean.

Implement

1. Inspect the relevant code before editing.
2. State a brief implementation plan in the conversation, then continue without waiting unless blocked.
3. Make the smallest coherent change that satisfies the issue.
4. Add or update tests for changed behavior where appropriate.
5. Avoid unrelated refactors, formatting churn, generated artifacts, and dependency changes.
6. Re-read affected code and consider error handling, compatibility, and edge cases.

Validate

Discover and run the repository's applicable checks, normally including:

• formatter or formatting check
• linter
• type checker
• focused tests
• broader tests when practical

Fix failures caused by your changes. Clearly distinguish pre-existing or environmental failures from regressions. Never claim a command passed unless you ran it and observed success.

Before committing:

1. Inspect git status --short.
2. Review the complete diff against the assigned base.
3. Remove accidental or unrelated changes.
4. Confirm no secrets or local-only files are included.

Create a local review checkpoint

1. Commit the changes locally with a message beginning with the uppercase issue ID, for example ENG-123: add request throttling.
2. Record the resulting commit hash.
3. Do not push the branch.
4. Do not create a pull request.
5. Leave the worktree and child Pi session intact so the user can inspect, amend, or extend the implementation.

Do not amend unrelated commits, rewrite shared history, update the base branch, or clean up the worktree.

Final report

End with this structure:

Status: ready-for-review | blocked | failed
Issue: <ID>
Branch: <branch>
Commit: <local commit hash or none>
Worktree: <absolute path>
Resume: cd <worktree> && PI_WORKTREE_AGENT=1 PI_WORKTREE_ROOT="$PWD" pi -c
Published: no

Summary:
- <what changed>

Checks:
- <command>: passed | failed | not run — <reason when relevant>

Risks and follow-up:
- <remaining concern or none>

Blocker:
- <reason, or none>

Use ready-for-review only when the requested implementation is committed locally and ready for user inspection. Use blocked when requirements, repository state, validation, or local commit creation prevent safe completion. Use failed for an unrecoverable implementation failure. Never describe the work as pushed or published.