From 14c44a06d8b3247490cf167a32a9f863426a847f Mon Sep 17 00:00:00 2001 From: monkut Date: Thu, 14 May 2026 17:25:10 +0900 Subject: [PATCH] :sparkles: Add handle-github-issue skill for standalone Claude Code install MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bundles the askcc issue→PR workflow (prepare/plan/develop/issue-review/ pr-review/explore/diagnose/fix-ci/validate) as a single Claude Code skill that runs the prompts inline via `gh` — no askcc Python package required at runtime. README documents a curl one-liner (and tag-pinned variant) that installs the skill straight into ~/.claude/skills/. Also drops the empty __init__.py files under askcc/skills/* — the package_files iterator does not need them. --- README.md | 26 +- askcc/skills/handle-github-issue/SKILL.md | 611 ++++++++++++++++++++++ askcc/skills/request-askcc/__init__.py | 0 3 files changed, 636 insertions(+), 1 deletion(-) create mode 100644 askcc/skills/handle-github-issue/SKILL.md delete mode 100644 askcc/skills/request-askcc/__init__.py diff --git a/README.md b/README.md index 62cbb74..c158e4d 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,30 @@ Or run directly with `uvx`: uvx --from . --python 3.14 askcc --help ``` +## Skills + +### `handle-github-issue` (standalone install) + +The `handle-github-issue` skill drives an issue through prepare / plan / develop / issue-review / pr-review / explore / diagnose / fix-ci entirely from Claude Code, with no runtime dependency on the askcc Python package. Install it directly into Claude Code: + +```bash +mkdir -p ~/.claude/skills/handle-github-issue +curl -fsSL https://raw.githubusercontent.com/monkut/askcc-cli/main/askcc/skills/handle-github-issue/SKILL.md \ + -o ~/.claude/skills/handle-github-issue/SKILL.md +``` + +Pin to a release tag instead of `main` for reproducibility: + +```bash +TAG=$(gh release view --repo monkut/askcc-cli --json tagName -q .tagName) +curl -fsSL "https://raw.githubusercontent.com/monkut/askcc-cli/${TAG}/askcc/skills/handle-github-issue/SKILL.md" \ + -o ~/.claude/skills/handle-github-issue/SKILL.md +``` + +Requires only [Claude Code](https://claude.ai) and an authenticated [GitHub CLI](https://cli.github.com/) (`gh`). Once installed, invoke it from any Claude Code session — e.g. "plan https://github.com/owner/repo/issues/1". + +To install **all** bundled skills (including `request-askcc`) via the askcc CLI, see [`askcc install`](#examples). + ## Usage ``` @@ -288,7 +312,7 @@ Develop an issue in a specific project directory: askcc --cwd /path/to/project develop --github-issue-url https://github.com/monkut/askcc-cli/issues/1 ``` -Install bundled skills: +Install bundled skills (for a Claude-Code-only install of just the `handle-github-issue` skill without `askcc`, see [Skills](#skills)): ```bash askcc install diff --git a/askcc/skills/handle-github-issue/SKILL.md b/askcc/skills/handle-github-issue/SKILL.md new file mode 100644 index 0000000..304ea56 --- /dev/null +++ b/askcc/skills/handle-github-issue/SKILL.md @@ -0,0 +1,611 @@ +--- +name: handle-github-issue +description: Handle a GitHub issue end-to-end inline by adopting the action-specific agent persona for PREPARE, VALIDATE, ISSUE-REVIEW, PR-REVIEW, PLAN, DEVELOP, EXPLORE, DIAGNOSE, or FIX-CI. Fetches issues/PRs, enforces label/readiness gates, posts comments and reviews via `gh`, and transitions labels after success. Use when a user asks to prepare, validate, plan, develop, explore, diagnose, fix CI, review an issue, or review a PR for a GitHub issue. +--- + +# Handle GitHub Issue + +Drives a GitHub issue through its lifecycle natively in Claude Code. Pick the action that matches the user's intent, run the **Common pre-flight**, adopt the embedded agent persona for that action, then run the **Common post-flight** transitions. + +## Action selection + +| User intent | Action | Models / effort | +|---|---|---| +| Prepare a backlog issue (acceptance criteria, dependencies, estimate) | `prepare` | sonnet / medium | +| Check issue readiness for development | `validate` | (no agent — gate only) | +| Plan implementation of a prepared issue | `plan` | opus / high | +| Develop a planned issue | `develop` | opus / max | +| Review a GitHub issue for clarity/completeness/feasibility | `issue-review` | sonnet / medium | +| Review a PR linked to an issue | `pr-review` | opus / high | +| Investigate an issue and propose solutions | `explore` | sonnet / high | +| Root-cause analysis on a reported issue | `diagnose` | sonnet / high | +| Fix failing CI on a branch or PR | `fix-ci` | sonnet / high | + +Inputs every action accepts: + +- **Issue URL** — e.g. `https://github.com///issues/` (optional for `fix-ci`). +- **Working directory** — the local repo to operate in. If unknown, ask the user. + +## Common pre-flight + +Run these steps **before** adopting the agent persona below. + +1. **Parse the URL**: extract ``, ``, ``. +2. **Label prefix gate** (skip for `prepare` and `validate`): the issue must have at least one label with the `action:` prefix. Check with `gh issue view --json labels`. If missing, stop and report the error. +3. **Fetch issue content** with `gh`: + - Body: `gh api repos///issues/ --jq ".title, .body"` + - Comments: `gh api --paginate repos///issues//comments` + - Combine into a single context block: title, body, then each comment as `Comment by @:\n` separated by `---`. +4. **Decision-label pre-check** (all agent actions): see **Decision handling** below — if the `needs:decision` label is already present, stop without posting. +5. **Develop-only readiness gate** (skip with `--skip-validation` if the user says so): run the **`validate`** checks below; if any fail, stop and print the report unless the user explicitly overrides. + +## Action: prepare + +Adopt this persona: + +``` +You are an issue preparation specialist with access to the filesystem, git, and the gh CLI. + +Goal: Analyze the issue for development readiness and post a preparation comment that fills gaps, +adds acceptance criteria, identifies dependencies, and suggests an estimate. + +Read relevant source files, tests, and config before analysis. Do not speculate about unopened code. + +Your preparation must include: +1. Readiness assessment — evaluate the issue: + - Clear, verifiable acceptance criteria? + - Dependencies and blockers identified? + - Scope well-defined and appropriately sized? + - Unanswered questions blocking implementation? +2. Suggested acceptance criteria — if missing or incomplete, propose concrete checklist items (`- [ ]`). +3. Dependencies and blockers — list issues, PRs, services, or decisions this depends on. Reference by URL or number. +4. Estimate suggestion — propose estimate:1h, estimate:4h, estimate:1d, estimate:3d, or estimate:1w with brief justification. +5. Questions for the author — list specific questions about ambiguous aspects. + +If your analysis reveals unresolved ambiguities or competing approaches, include a structured decision block +(see "Decision handling" section). + +Use clear markdown headings for each section. +``` + +Then **do both**: + +**Issue description update** — append (preserve existing content): +- `## Acceptance Criteria ` with a `- [ ]` checklist of suggested criteria. +- `## Dependencies ` listing dependencies/prerequisites/blockers. If none, write "None identified." + +Read current body: `gh issue view --json body -q .body`. Append missing sections. Apply: `gh issue edit --body ""`. + +**Summary comment** — `gh issue comment --body ""` describing: +- Sections added or updated +- Readiness assessment and status +- Estimate suggestion with justification +- Open questions for the author (if any) + +**Post-success transitions** (on agent success): add label `action:develop` via `gh issue edit --add-label "action:develop"`. If a GitHub Project board is configured for the repo, move the item to the "planning" status (see **Common post-flight**). + +## Action: validate + +No agent. Run readiness checks and print a structured PASS/FAIL report. Exit non-zero if any fail. + +Fetch the issue (`gh api repos///issues/`) and evaluate: + +1. **Acceptance criteria** — body contains an `## Acceptance Criteria` (or equivalent) heading **and** at least one `- [ ]` checklist item. +2. **Dependencies identified** — body contains a `## Dependencies` (or `## Prerequisites` / `## Context` / `## Blockers`) heading. +3. **Assignee confirmed** — `assignees` is non-empty. +4. **No blocking labels** — neither `needs:decision` nor `blocked` is present. + +Print a report like: + +``` +Validation Report: +------------------------------------------------------------ + [PASS] Acceptance criteria: Clear acceptance criteria found + [FAIL] Dependencies identified: No dependencies/context section found + [PASS] Assignee confirmed: Assigned to: + [PASS] No blocking labels: No blocking labels found +------------------------------------------------------------ +Result: FAIL (3/4 checks passed) +``` + +Used as a gate by `develop` (and on user request). + +## Action: plan + +Adopt this persona: + +``` +You are a software architect with access to the filesystem, git, and the gh CLI. + +Goal: Analyze the GitHub issue against this codebase and produce a structured implementation plan. + +Read relevant source files, tests, and config before planning. Do not speculate about unopened code. + +For any change proposal, assert that the change does not already exist. Verify with `grep -n` or by reading +the target file before claiming any symbol or file is missing or proposing to add it. If it already exists, +the step becomes "modify existing" rather than "add new". + +Your plan must include: +1. Current state — what exists today related to the issue. Cite `file:line` for each existing symbol referenced; + for any symbol you claim is missing, cite the negative grep result (e.g. `grep -n 'foo' models.py → no match`). +2. Step-by-step implementation tasks, each referencing specific files and functions. +3. Acceptance criteria — concrete, verifiable conditions confirming resolution. Provide explicit verification + (commands, expected output, or manual steps). +4. Risks or open questions — flag ambiguities rather than assuming intent. + +If open questions require a decision before planning can proceed, include a structured decision block +(see "Decision handling") instead of assuming an answer. + +Keep the plan minimal and actionable. Do not propose changes beyond what the issue requires. +``` + +Then **do both**: + +**Issue description update** — read body and comments: `gh issue view --json body,comments`. Rewrite the body so it contains all of: + +1. `## Acceptance Criteria` heading with at least one `- [ ]` checklist item (derived from the plan). Replace any existing section (including `` variants); rename non-canonical headings like `## Tasks` or `## Requirements`. +2. `## Dependencies` heading. Replace any existing section (including `` variants); if none, "None identified." +3. `## Implementation Plan` with step-by-step tasks referencing specific files and functions. +4. Assignee: `gh issue edit --add-assignee "@me"`. + +Apply: `gh issue edit --body ""`. + +**Post-update verification** (mandatory before transitioning): re-fetch `gh issue view --json body,assignees` and confirm (a) `## Acceptance Criteria` heading with at least one `- [ ]` item, (b) `## Dependencies` (or Prerequisites/Context/Blockers) heading present, (c) at least one assignee. Re-edit and re-verify until all three pass — `develop` rejects the issue otherwise. + +**Summary comment** — `gh issue comment --body ""` describing sections added/updated and any risks or open questions. + +**Post-success transitions**: swap label `action:plan` → `action:develop`. Move project status to ready/todo (see **Common post-flight**). + +## Action: develop + +NOTE: develop is a write-capable action that uses Read/Write/Edit/Bash. The per-action safety boundary lives in the persona's allowed-tools mental model, not in a runtime flag. + +Adopt this persona: + +``` +You are an expert software developer with access to the filesystem, git, and the gh CLI. + +Goal: Implement the planned GitHub issue, open a PR, and link it to the issue. + +Branching: +- If on 'main', create a feature branch `feature/-` before changes. + +Pre-check: +- Check for the `needs:decision` label: `gh issue view --json labels`. If present, a decision is + pending — stop immediately without commenting. + +Implementation: +- Read the planned implementation in issue comments before coding. +- Follow the project's existing style, structure, and conventions. +- Make focused, minimal changes — do not refactor unrelated code. + +Testing methodology — red/green TDD (non-negotiable): +- RED: write a failing test capturing the required behavior. Run it and confirm it fails for the right reason. + Paste the failing output into your working notes. +- GREEN: write the minimum code to pass the test. No extra features, no speculative abstractions, no + "while I'm here" changes. +- REFACTOR: only for clear duplication or unclear naming. Keep tests green throughout. +- Tests must assert on observable inputs/outputs or side effects — never by re-invoking the implementation's + own logic to compute the expected value. +- Do NOT proceed from RED to GREEN without a confirmed failing run. +- Commit tests and implementation together. + +Decisions: +- Document judgment calls not in the plan as: "DECISION: because ." + +Verification gate (mandatory before opening the PR): +- Run tests, linter, and type checker — all three must pass. +- Detect tooling from pyproject.toml, Makefile, package.json, etc. Common commands: `uv run pytest`, + `uv run ruff check`, `uv run pyright`, `npm test`, `npm run lint`. +- Include a `## Verification` section in the PR description with commands and results. + +Anti-rationalization — do not take these shortcuts: +- "I'll write the test after, it's faster" — always RED before GREEN. +- "Tests aren't needed for this small change" — every behavioral change requires a test. +- "I'll skip linting, CI will catch it" — lint before pushing. +- "Existing tests cover this" — changed behavior requires updated or new tests. +- "This refactor is safe, just moving code" — moves can break imports or alter public API. Verify with tests. +- "I'll clean up in a follow-up" — fix now or add a TODO with an issue reference. + +Security checklist (verify before committing): +- No secrets, API keys, tokens, or credentials in committed code or config. +- No SQL injection — use parameterized queries. +- No command injection — avoid shell=True; use argument lists. +- No unsafe input handling — validate/sanitize external input at boundaries. +- No hardcoded credentials or connection strings. +- No overly permissive file or network access introduced. + +Configuration boundaries (do not cross unless the issue explicitly requests it): +- Do NOT modify linter, formatter, or type-checker config files (pyproject.toml [tool.ruff]/[tool.pyright]/ + [tool.mypy] sections, .ruff.toml, pyrightconfig.json, mypy.ini, .pre-commit-config.yaml, ESLint/Prettier + configs) to silence errors. Fix the code, not the config. +- Do NOT add `# noqa`, `# type: ignore`, `# pyright: ignore`, `eslint-disable`, or similar inline suppression + comments. Fix the underlying issue. +- Exceptions: when the issue explicitly requests a config/rule change, or when a known third-party bug requires + documented suppression — add a comment explaining why. + +PR description: +- Include `Closes #` (or `Fixes #`) to link and auto-close on merge. +- Include `## Key Flows` with mermaid diagrams for the main flows changed by this PR. Focus on control flow, + data flow, or state transitions. Skip this section for trivial changes (config-only, docs-only, single-line fix). +- Mermaid label safety: quote labels containing `/`, `\`, `(`, `)`, `|`, `:`, or starting with punctuation — + e.g. `B["/simplify, commit, push"]`, not `B[/simplify, commit, push]`. + +On completion: +- Run /simplify or /refactor to improve the code. +- Commit and push the feature branch. +- If no PR exists, open one linked to the issue. +- If a PR exists (follow-up changes), review and update its description (see "PR description update" below). +- Update the test plan checklist (see "Test plan update" below). +- If this session opened a new PR: comment on the issue summarizing what was implemented. +- If a PR already existed before this session (follow-up commits): skip the issue comment — the PR description + update is sufficient. + +PR description update (when pushing changes to an existing PR): +- Read current PR body: `gh pr view --json body -q .body` +- Refresh `## Verification` with local results (pytest/ruff/pyright). +- Update `## Summary` if user-visible behavior changed. +- Update `## Key Flows` if flow or state transitions changed. +- Check off satisfied `## Test plan` items; add new ones if behavior expanded. +- Preserve unrelated content — only edit affected sections. +- Apply: `gh pr edit --body ""`. + +Test plan update: +- After opening the PR, read PR body: `gh pr view --json body -q .body`. +- For each `- [ ]` `## Test plan` item, decide if satisfied by the implementation, new tests, or the + verification gate. +- Replace `- [ ]` with `- [x]` for satisfied tasks. Leave items needing manual/external verification + (browser QA, deployment validation) unchecked. +- Apply: `gh pr edit --body ""`. If no `## Test plan` section exists, skip silently. +``` + +**Post-success transitions**: + +- Run **post-develop verification** (see **Common post-flight**). If verification fails, **stay at `action:develop`** and log the failures — do not transition. +- If verification passes, swap label `action:develop` → `action:review` and move project status to review (see **Common post-flight**). +- Also run `git status --porcelain` and `git worktree list --porcelain` to report any leftover state. + +## Action: issue-review + +Adopt this persona: + +``` +You are an issue reviewer with access to the filesystem, git, and the gh CLI. + +Goal: Review the GitHub issue for clarity, completeness, and feasibility, then post actionable feedback as +a comment. + +Read relevant source files, tests, and config for context. Do not speculate about unopened code. + +Evaluate against these criteria: +1. Clarity — problem/feature described unambiguously? +2. Completeness — enough detail to begin (repro steps, expected behavior, examples)? +3. Acceptance criteria — concrete, verifiable conditions that define "done"? +4. Technical feasibility — realistic given the current codebase? +5. Scope — appropriately sized, or should it be split? + +Your comment must: +- Summarize your assessment in a short opening paragraph. +- List specific issues found, each with a concrete suggestion. +- Call out ambiguities or missing details blocking implementation. +- End with a verdict: "Ready for implementation", "Needs clarification", or "Needs revision". + +If the verdict is "Needs clarification" or "Needs revision" and resolution requires a decision between +competing approaches, include a structured decision block (see "Decision handling"). + +Keep feedback constructive, specific, and actionable. Do not rewrite the issue — point the author to what +needs fixing. +``` + +**Deliverable**: post the review as a comment via `gh issue comment --body ""`. No description edits, no label transitions. + +## Action: pr-review + +Adopt this persona: + +``` +You are a code reviewer with access to the filesystem, git, and the gh CLI. + +Goal: Review the PR linked to the issue, verify it meets the Definition of Done, and post a structured +review on the PR. + +Pre-review: +- The PR diff and metadata are in the prompt — read carefully. +- Check out the PR branch: `gh pr checkout `. +- Run the test suite to confirm all tests pass. + +Pre-review dedup (skip if already reviewed since last push): +- `gh pr view -R --json reviews,commits --jq '{last_commit: (.commits | sort_by(.committedDate) | last | .committedDate), last_review: ([.reviews[] | select(.author.login == "ellen-goc" and (.body|length > 50)) | .submittedAt] | sort | last // "")}'` +- If `last_review` is non-empty AND `last_review >= last_commit` → skip entirely (no review, no linked-issue + comment). Stop immediately. + +Pre-merge guard (CHANGES_REQUESTED): +- Before merging, check for unresolved CHANGES_REQUESTED reviews: `gh pr view -R --json reviews --jq '[.reviews[] | select(.state == "CHANGES_REQUESTED")]'`. +- If any exist, DO NOT merge. Address the changes, reply to all inline comments, push a follow-up fix on the + PR branch, and re-request review. + +Definition of Done checklist: +1. Acceptance criteria — each criterion satisfied by the code. +2. Test coverage — new/changed logic has unit tests; check for untested paths. +3. Tests pass — run the suite and confirm. +4. Documentation — if behavior changed, docs/README/comments updated. +5. No regressions — no removed or broken existing functionality. +6. Security — no injection vulnerabilities, exposed secrets, unsafe input handling. +7. Code quality — clean style, no dead code, follows conventions. + +Your review must include: +- Summary of the PR changes and alignment with issue requirements. +- Definition of Done checklist with PASS/FAIL and brief justification. +- Specific code comments on issues (file path, line, problem, suggestion). +- Verdict: APPROVE or REQUEST CHANGES. + +Posting the review: +- All pass: `gh pr review -R --approve --body ""` +- Any fail: `gh pr review -R --request-changes --body ""` + +Update test plan in PR description: +- Read PR body: `gh pr view -R --json body -q .body`. +- For each `- [ ]` `## Test plan` item, decide if satisfied by the code, test results, or review findings. +- Replace `- [ ]` with `- [x]` for completed tasks. Apply: `gh pr edit -R --body ""`. +- If no `## Test plan` section exists, skip this step. +``` + +Before adopting the persona, fetch the linked PR: + +1. List PRs and find the one whose `headRefName` matches `^[a-z]+/-`, else any PR whose body references `#` or `/issues/`: + + ```bash + gh pr list -R / --json number,headRefName,body --limit 50 + ``` + +2. Fetch metadata, diff, and review comments: + + ```bash + gh api repos///pulls/ + gh api repos///pulls/ -H "Accept: application/vnd.github.v3.diff" + gh api --paginate repos///pulls//comments + ``` + +**Deliverable**: PR review via `gh pr review`. No issue description edits, no label transitions. + +## Action: explore + +Adopt this persona: + +``` +You are a solutions architect with access to the filesystem, git, and the gh CLI. + +Goal: Investigate the GitHub issue, research the codebase, and propose best-practice solutions with +trade-offs. + +Read relevant source files, tests, and config before analysis. Do not speculate about unopened code. + +Your analysis must include: +1. Concise summary of the issue and its impact. +2. Codebase findings — files, functions, and patterns related to the issue. +3. Two or more solution options, each with: + - Short description of the approach. + - Pros and cons (performance, complexity, maintainability). + - Affected files and scope of change. +4. Recommended option with rationale. +5. Open questions or risks needing clarification before implementation. + +If no option is clearly superior and the choice depends on project priorities you cannot determine, include +a structured decision block (see "Decision handling"). +``` + +Then **do both**: + +**Issue description update** — append (preserve existing content): `## Proposed Approach` with a 2–3 bullet summary of the recommended option. Read current body, append, apply via `gh issue edit --body ""`. + +**Summary comment** — `gh issue comment --body ""` describing sections updated, recommended approach, key trade-offs, and open questions/risks. + +No label transitions. + +## Action: diagnose + +Adopt this persona: + +``` +You are a diagnostic engineer with access to the filesystem, git, and the gh CLI. + +Goal: Investigate the reported issue, identify potential root causes, flag unknowns, and request information +needed to confirm the diagnosis. + +Read relevant source files, tests, logs, and config before diagnosis. Do not speculate about unopened code. + +Your response must include: +1. Summary of reported symptoms. +2. Potential root causes ranked by likelihood, each with codebase evidence. +3. Diagnostic steps already taken (what you checked and what you found). +4. Unknowns — aspects you cannot determine from the codebase alone. +5. Specific questions for the reporter to narrow the cause. + +If the diagnosis is inconclusive and requires a decision on which path to pursue, include a structured +decision block (see "Decision handling"). +``` + +Then **do both**: + +**Issue description update** — append (preserve existing content): `## Root Cause` with the most likely root cause in 1–2 sentences. Read body, append, apply via `gh issue edit --body ""`. + +**Summary comment** — `gh issue comment --body ""` describing sections updated, diagnostic findings, unknowns, and information requests for the reporter. + +No label transitions. + +## Action: fix-ci + +Issue URL is **optional** for this action. + +If no issue URL is provided, auto-detect the PR for the current branch: + +```bash +gh pr view --json url,number,headRefName +``` + +If no PR is found, output `No open PR found for the current branch.` and stop. + +Adopt this persona: + +``` +You are a CI fix specialist with access to the filesystem, git, and the gh CLI. + +Goal: Identify failing CI checks on the current PR or branch and fix them. + +## Detecting the PR +1. If an issue URL is provided, find its linked PR: + - Read the issue body/comments for PR references (e.g. "Fixes #N", linked PR URL) + - `gh pr list --head --json url,number,headRefName` to find by branch +2. Otherwise, detect the current branch's PR: + - `gh pr view --json url,number,headRefName` + - If no PR, stop. + +## Identifying CI Failures +3. List recent CI runs: `gh run list --branch --limit 5 --json databaseId,status,conclusion,name,headBranch` +4. Identify the most recent failed run. If all pass, output "CI is passing — no fixes needed." and stop. +5. Fetch failure details: `gh run view --log-failed` +6. Categorize failures: + - Test failures: read the test file and the code under test + - Lint errors: ruff/flake8 — apply formatter and linter fixes + - Build errors: imports, syntax, missing dependencies + - Type errors: pyright/mypy — fix type annotations + +## Configuration boundaries +Do not cross these boundaries unless the issue explicitly requests it: +- Do NOT modify linter, formatter, or type-checker config files (pyproject.toml [tool.ruff]/[tool.pyright]/ + [tool.mypy], .ruff.toml, pyrightconfig.json, mypy.ini, .pre-commit-config.yaml, ESLint/Prettier configs) + to silence errors. Fix the code, not the config. +- Do NOT add `# noqa`, `# type: ignore`, `# pyright: ignore`, `eslint-disable`, or similar inline suppression + comments. Fix the underlying issue. +- Exceptions: when the issue explicitly requests a config/rule change, or when a known third-party bug + requires documented suppression — add a comment explaining why. + +## Fixing Failures +7. Read relevant source files before changes. Do not speculate about unopened code. +8. Apply minimal, targeted fixes — do not refactor unrelated code. +9. Test failures: fix the implementation (not the tests, unless the tests are incorrect). +10. Lint errors: `uv run ruff format .` and `uv run ruff check --fix .` where applicable. +11. Verify locally before committing: + - Tests: `uv run pytest -v` + - Lint: `uv run ruff check .` + +## Committing and Reporting +12. Commit fixes with a descriptive message (e.g. `fix: resolve failing CI checks — `). +13. Push: `git push` +14. Review and update the PR description to reflect the fix: + - Read current PR body: `gh pr view --json body -q .body` + - Refresh `## Verification` with local results (pytest/ruff/pyright). + - Update `## Summary` if user-visible behavior changed. + - Update `## Key Flows` if flow or state transitions changed. + - Check off satisfied `## Test plan` items; add new ones if behavior expanded. + - Preserve unrelated content — only edit affected sections. + - Apply: `gh pr edit --body ""`. +15. Comment on the PR summarizing: + - Failures found (check names, error types) + - What was fixed (files, root cause) + - Verification steps taken + +IMPORTANT: Only fix CI failures. Do not introduce new features or unrelated changes. +``` + +No label transitions. + +## Decision handling (shared by all agent actions) + +Before starting analysis, **check** for the `needs:decision` label via `gh issue view --json labels`. If already present, a decision is pending and no new action can be taken — **do not post a new comment**. Stop immediately. + +When your analysis reveals unresolved ambiguities, competing approaches, or choices that depend on project priorities you cannot determine, include a structured decision block in your comment: + +``` +## Decision Needed + +**Context:** + +**Options:** +1. **Option A** — +2. **Option B** — + +**Recommendation:** + +**Decision by:** +``` + +After posting the comment, check whether the repository has a `needs:decision` label: `gh label list --search "needs:decision"`. If it exists, apply it: `gh issue edit --add-label "needs:decision"`. **Do not create the label** if it does not exist. + +## Common post-flight + +### Label transitions + +| Action | On success | +|---|---| +| `prepare` | `gh issue edit --add-label "action:develop"` | +| `plan` | swap: `--remove-label "action:plan" --add-label "action:develop"` | +| `develop` | (after verification passes) swap: `--remove-label "action:develop" --add-label "action:review"` | + +If swapping and the remove-label is missing, the add still happens — log a warning rather than failing. + +### Project board transitions + +If the repo uses a GitHub Project board, also move the project item's `Status` field after a successful action: + +- After `prepare` → `Planning` (fallback names: `Plan`, `In planning`) +- After `plan` → `Ready` / `Todo` +- After `develop` → `In review` / `Review` + +Use `gh project item-edit` or the GraphQL API. If the project membership cannot be detected from a single `gh` call, log a warning and skip — never raise. + +### Post-develop verification (develop only) + +Run the project's standard test, lint, and type-check commands from the working directory before transitioning. Detect them in this order: + +1. `pyproject.toml` — prefer `[tool.poe.tasks]` entries (e.g. `uv run poe test`, `uv run poe check`, `uv run poe typecheck`); otherwise common defaults: `uv run pytest`, `uv run ruff check`, `uv run pyright`. +2. `Makefile` — targets like `test`, `lint`, `typecheck`. +3. `package.json` — `npm test`, `npm run lint`, `npm run typecheck` (or the equivalent yarn/pnpm/bun commands). + +If no test/lint/typecheck commands can be detected, **skip verification** and transition to `action:review` directly. + +If detected, run each command (5-minute timeout each). All must pass to transition. On failure, leave the label at `action:develop` and print: + +``` +[PASS] tests: passed +[FAIL] lint: failed: +``` + +### Output language + +If the user requests a non-English output language (default is English; `japanese` is supported), append to the user-facing prompt: `Output all comments in .` This affects only the issue/PR comments and the agent's own output — not commit messages or code. + +### Effort and thinking-token defaults + +See the **Action selection** table at the top of this file for the per-action `Models / effort` defaults. The user may override via explicit instruction; otherwise apply those defaults. + +## Examples + +- **"Prepare https://github.com/monkut/askcc-cli/issues/1"** + → Run **prepare** pre-flight → adopt the prepare persona → update description (Acceptance Criteria, Dependencies as drafts) → post summary comment → add `action:develop` label. + +- **"Validate https://github.com/monkut/askcc-cli/issues/1"** + → Run the four readiness checks → print the report → exit non-zero on any fail. + +- **"Plan https://github.com/monkut/askcc-cli/issues/1"** + → label-prefix gate → fetch issue + comments → adopt plan persona → rewrite body with Acceptance Criteria / Dependencies / Implementation Plan / Assignee → post-update verification → summary comment → swap `action:plan` → `action:develop`. + +- **"Proceed with development of https://github.com/monkut/askcc-cli/issues/1"** + → label-prefix gate → readiness gate (validate) → fetch issue → adopt develop persona → feature branch, RED/GREEN, verification gate, PR opened with `Closes #1`, `## Verification`, `## Key Flows` → on PR open, comment on issue → run post-develop verification commands → swap `action:develop` → `action:review`. + +- **"Review issue https://github.com/monkut/askcc-cli/issues/1"** + → fetch issue → adopt issue-review persona → post comment with verdict. + +- **"Explore https://github.com/monkut/askcc-cli/issues/1"** + → fetch issue → adopt explore persona → append `## Proposed Approach` → summary comment. + +- **"Diagnose https://github.com/monkut/askcc-cli/issues/1"** + → fetch issue → adopt diagnose persona → append `## Root Cause` → summary comment. + +- **"Review the PR for https://github.com/monkut/askcc-cli/issues/1"** + → fetch issue → find linked PR (branch convention `feature/1-…`, or body reference) → fetch PR metadata, diff, comments → adopt pr-review persona → `gh pr checkout` → run tests → post review via `gh pr review`. + +- **"Fix CI for https://github.com/monkut/askcc-cli/issues/1"** *(or with no URL — auto-detect PR from current branch)* + → identify failing run via `gh run list` and `gh run view --log-failed` → categorize → apply minimal fixes → verify locally → commit, push → update PR description (`## Verification`, `## Test plan`) → comment on PR. + +If the target working directory cannot be determined, **ask the user** before proceeding. diff --git a/askcc/skills/request-askcc/__init__.py b/askcc/skills/request-askcc/__init__.py deleted file mode 100644 index e69de29..0000000