kody

name	kody
description	Write Kody-Engine-ready GitHub issues and interact with the Kody pipeline (trigger, monitor, verify)
version	1.0.0

Kody — GitHub Issue Writing & Pipeline Interaction

Use this skill when working in a repository that has Kody Engine installed. It has two parts:

1. Writing issues — so Kody understands the task correctly on the first try
2. Pipeline interaction — triggering, monitoring, and verifying Kody pipeline runs

---

Part 1 — Writing Kody-Ready Issues

What Kody reads from an issue

Kody reads the issue body + comments to understand the task. Specifically:

• The issue body becomes the primary task description (written to .kody/tasks/<task-id>/task.md)
• The first 5 comments are included as context
• The last 10 comments are included (for ongoing discussions)
• Labels are read to determine complexity and task type

Issue body structure

Structure the issue body with these sections, in order:

## Goal

One clear sentence describing what needs to be built or fixed.

## Context

Why this is needed — background, motivation, user story.
1–3 paragraphs. Be specific about the problem, not the solution.

## Acceptance Criteria

- [ ] Criterion 1 (observable, testable)
- [ ] Criterion 2
- [ ] Criterion 3

## Scope

**In scope:** what Kody should implement.
**Out of scope:** what Kody should skip or what another issue covers.

What makes an issue Kody-friendly

Good	Bad
Single, well-scoped task	Multiple unrelated tasks in one issue
Concrete acceptance criteria	Vague goals like "improve performance"
Specific file/feature references	"Fix the frontend"
Explains why, not just what	Just describing the implementation
Mentions affected files/modules	No context about where to work

Labels Kody reads

Add these labels before triggering the pipeline to control behavior:

Label	Effect
kody:low	Skip plan stage and review stage — Kody builds directly
kody:medium	Skip review-fix stage (review runs but failures are not auto-retried)
kody:high	Full pipeline including risk gate — Kody pauses for @kody approve before building
kody:feature	Labels the task as a feature in the PR title (feat: prefix)
kody:bugfix	Labels the task as a bug fix (fix: prefix)
kody:refactor	Labels as refactoring (refactor: prefix)
kody:docs	Labels as documentation (docs: prefix)

Tip: If you don't set a complexity label, Kody's taskify stage infers it from the issue scope. Set kody:low explicitly if you want a fast, focused build with no review overhead.

What to avoid

• Multi-issue issues — split them. Kody processes one task per pipeline run.
• Solution-first descriptions — describe the problem, not the implementation. Let Kody propose the solution in its plan.
• Missing acceptance criteria — without them, there's no clear definition of done.
• References to other issues — if work depends on another issue being done first, say so explicitly in Scope.

---

Part 2 — Triggering the Kody Pipeline

Who can trigger Kody

Only users with these GitHub author associations can trigger Kody:

• OWNER — repo owner
• MEMBER — organization member
• COLLABORATOR — accepted collaborator

Bot accounts, contributors, and first-time contributors are blocked and receive an error comment.

Trigger commands

Post a comment on the GitHub issue (or PR) using one of these:

@kody              # Full pipeline (taskify → plan → build → verify → review → ship)
@kody full         # Same as @kody (explicit)
@kody rerun        # Resume from the last failed stage (uses previous task-id)
@kody rerun <id>   # Resume a specific task-id from the last failed stage
@kody rerun <id> --from <stage>  # Resume from a specific stage (e.g. --from build)
@kody fix          # Fix the last failed run — diagnose and push fixes
@kody fix-ci       # Fix CI failures only (detect → fix → push without full pipeline)
@kody review       # Review the latest PR
@kody review <url> # Review a specific PR URL
@kody bootstrap    # Re-run bootstrap (analyze repo, regenerate memory files)
@kody approve      # Approve a paused pipeline (answers the risk gate for kody:high issues)
@kody ask <q>      # Ask a question — Kody posts an answer as a comment and pauses
@kody hotfix       # Hotfix mode — skip plan and review stages
@kody decompose    # Decompose this issue into sub-tasks

Passing feedback to a pipeline run

Append feedback after the command — it becomes the feedback field:

@kody  # Full pipeline with no extra feedback
@kody --feedback "Use the new API endpoint instead of the old one"
@kody approve --feedback "Yes, go ahead with the changes"

---

Part 3 — Monitoring the Pipeline

Label lifecycle

Kody sets these labels in sequence as the pipeline progresses. Watch them to track status:

kody:planning  →  kody:building  →  kody:verifying  →  kody:review
→  kody:fixing  →  kody:shipping  →  kody:done (success)
                                                   ↘  kody:failed
kody:waiting   # Pipeline paused — Kody is waiting for answers to questions
kody:paused    # Pipeline paused — awaiting @kody approve (risk gate for kody:high)

In CI runs, labels are the only persistent state between steps (.kody/tasks/ doesn't survive across CI jobs). If a pipeline fails and is retried, Kody reads these labels to determine where to resume.

What Kody posts as comments

Kody posts these comment types on the issue during the pipeline:

Comment	Meaning
🚀 Kody pipeline started: \task-id` (logs)`	Pipeline triggered, logs linked
Questions listed in a block	Pipeline paused at question gate — answer each question in a comment
🛑 **Risk gate: HIGH complexity — awaiting approval** + plan summary	Pipeline paused at risk gate — use @kody approve to proceed
To approve: \@kody approve``	Follow-up after risk gate warning
✅ Fix pushed to PR #N	Review-fix stage pushed changes to the PR
🎉 PR created: https://...	Pipeline succeeded — PR link posted
## Pipeline Summary (table)	Stage-by-stage status, duration, and retry count
❌ Pipeline failed at **stage-name**	Pipeline failed — check the stage details

Reading the pipeline summary

The pipeline summary comment is a markdown table:

## Pipeline Summary

| Stage   | Status  | Duration | Retries |
| ------- | ------- | -------- | ------- |
| taskify | ✅ PASS | 12s      | 0       |
| plan    | ✅ PASS | 45s      | 0       |
| build   | ✅ PASS | 3m 12s   | 0       |
| verify  | ✅ PASS | 1m 08s   | 1       |
| review  | ✅ PASS | 28s      | 0       |
| ship    | ✅ PASS | 18s      | 0       |

• Status ✅ PASS — stage succeeded
• Status ❌ FAIL — stage failed; check the error comment above the summary
• Retries > 0 — Kody self-healed via retry; the summary shows how many attempts were needed

---

Part 4 — Verifying Success & Triaging Failures

Pipeline succeeded — what to check

1. PR link in the success comment (🎉 PR created: ...)
2. Pipeline summary — all stages show ✅ PASS
3. Labels — kody:done + kody:success on the issue
4. PR body — should contain Closes #<issue-number> and a summary of changes

If the PR was created but labels aren't updated (rare CI timing issue), manually refresh by checking the PR status.

Pipeline failed — triage path

1. Find the failure stage — look for ❌ Pipeline failed at **stage-name** in the comments
2. Check the error message — the failure comment contains the error details
3. Read the retry count — if retries > 0, Kody already tried to self-heal
4. Choose your action:

@kody fix          # Best for: build errors, lint errors, test failures
@kody rerun --from build  # Best for: Kody pushed bad code, you fixed it locally and want to resume from build
@kody rerun --from plan   # Best for: plan was wrong or you want Kody to re-plan from scratch
@kody bootstrap    # Best for: verify stage fails due to missing tools/setup

Verify stage failures

Stage	Common failure	Fix command
taskify	Issue body too vague	Edit the issue body with clearer acceptance criteria, then @kody rerun --from taskify
plan	Kody proposed wrong approach	Add guidance in a comment, then @kody rerun --from plan
build	Kody wrote broken code	@kody fix — Kody diagnoses and fixes
verify	Tests/lint/typecheck fail	@kody fix — Kody runs diagnosis and retries
review	Kody's own review found issues	@kody (standard full pipeline) — review-fix runs automatically
ship	Push/auth error	Check that the branch doesn't exist and GitHub token is valid, then @kody rerun --from ship

Question gate — Kody is waiting for you

If Kody posts a list of questions and the issue shows kody:waiting:

1. Answer each question by posting a comment with the answers
2. Kody reads the comment and resumes the pipeline automatically

You don't need to use any special command — just post a regular comment with the answers.

Risk gate — high complexity waiting for approval

If the issue shows kody:high and Kody posted the risk gate comment with a plan summary:

1. Review the plan summary in the comment
2. Approve or redirect:

   @kody approve                    # Approve as-is
   @kody approve --feedback "Yes, but use the v2 API instead"  # Approve with guidance
   

   After approval, Kody resumes from the build stage (not from scratch).

---

Summary — Quick Reference

Goal	Action
Start a full pipeline	Comment @kody on the issue
Monitor progress	Watch kody:* labels
Answer questions	Post a regular comment with answers
Approve high-risk task	Comment @kody approve
Fix a failure	Comment @kody fix
Resume a specific task	Comment @kody rerun <task-id> --from <stage>
Create Kody-ready issue	See Part 1 above