@devran-ai/kit 4.1.0

package/.agent/workflows/pr-fix.md

@@ -0,0 +1,163 @@
+---
+description: Fix PR issues from review comments. Fetch findings, prioritize by severity, implement fixes with evidence, verify, push, and post resolution summary with reviewer attribution.
+version: 1.1.0
+sdlc-phase: build
+skills: [pr-toolkit, verification-loop]
+commit-types: [fix]
+---
+
+# /pr-fix — Pull Request Fix Workflow
+
+> **Trigger**: `/pr-fix <url>` · `/pr-fix <owner/repo>#<number>` · `/pr-fix #<number>`
+> **Lifecycle**: Build — remediation after review, before re-review
+
+> Standards: See `rules/workflow-standards.md` (artifact discipline, evidence standard, governance)
+
+> [!CAUTION]
+> This workflow modifies code and pushes to the PR branch. Ensure write access and coordinate with PR author if needed.
+
+---
+
+## Critical Rules
+
+1. **REVIEWER ATTRIBUTION** — every fix MUST credit the reviewer who flagged it (stated once, applies to all steps and output)
+2. Fetch ALL review comments (humans AND bots) before implementing any fix
+3. Prioritize fixes: CRITICAL → HIGH → MEDIUM → LOW — never skip severity levels
+4. Run `/review` pipeline after all fixes before pushing — never push broken code
+5. Never modify code unrelated to review findings — stay scoped
+6. Atomic commits — one fix per commit referencing the finding (exception: related doc fixes in same file)
+
+---
+
+## Argument Parsing
+
+| Command | Action |
+| :--- | :--- |
+| `/pr-fix #<number>` | Fix PR in current repo |
+| `/pr-fix <url>` | Fix PR at GitHub URL |
+| `/pr-fix #<number> --critical-only` | Fix only CRITICAL findings |
+| `/pr-fix #<number> --dry-run` | Show fix plan without implementing |
+
+---
+
+## Steps
+
+### Step 1: Parse PR Reference and Validate
+
+// turbo
+
+Parse PR reference, validate PR is open. If closed/merged → **STOP**.
+
+### Step 2: Fetch ALL Review Comments
+
+```bash
+gh api repos/<owner>/<repo>/pulls/<number>/reviews
+gh api repos/<owner>/<repo>/pulls/<number>/comments
+gh api repos/<owner>/<repo>/issues/<number>/comments
+gh pr diff <number> --repo <owner/repo>
+```
+
+For each comment extract: **Reviewer**, **Type** (inline/general), **Finding**, **Severity**, **Suggested fix**, **Status**. Skip resolved/outdated comments.
+
+**Bot parsing**: Gemini → `Medium/High Priority` labels + `Suggested change` blocks. CodeRabbit → severity badges. SonarCloud → quality gate issues.
+
+### Step 3: Categorize and Prioritize
+
+| Priority | Category | Examples |
+| :--- | :--- | :--- |
+| P0 | CRITICAL | Security, data loss, crashes |
+| P1 | HIGH | Broken functionality, test failures |
+| P2 | MEDIUM | Doc inconsistencies, naming |
+| P3 | LOW/NIT | Suggestions, preferences |
+
+Generate fix plan table: `# | Priority | Reviewer | File:Line | Finding | Planned Fix`
+
+If `--dry-run` → display plan and **STOP**. If `--critical-only` → filter to P0.
+
+### Step 4: Checkout PR Branch
+
+```bash
+git fetch origin <head-branch> && git checkout <head-branch> && git pull origin <head-branch>
+```
+
+### Step 5: Implement Fixes
+
+For each fix (P0 → P3 order):
+1. Read file, record before state with line number
+2. Implement fix addressing reviewer's exact concern
+3. Record after state
+4. Verify fix, commit:
+```bash
+git commit -m "fix(review): <description>
+
+Addresses @<reviewer>'s finding at <file>:<line>"
+```
+
+**Guidelines**: Address exact concern — no over-fixing. Apply bot `Suggested change` blocks when valid. Verify cross-file consistency after each fix. Closely related fixes in same file from same reviewer may be grouped with documented reason.
+
+### Step 6: Run Verification
+
+Run `/review` pipeline (lint → type-check → tests → security → build). Record per-gate status. Max 3 retry cycles on failure.
+
+### Step 7: Push Fixes
+
+```bash
+git push origin <head-branch>
+```
+
+### Step 8: Post Resolution Summary
+
+Post comment on PR with fixes table, before/after diffs, verification results, and disposition. Re-request review from human reviewers via `gh pr edit --add-reviewer`.
+
+---
+
+## Output Template
+
+```markdown
+## PR Fix Complete: #{number} — {title}
+
+| Field | Value |
+| :--- | :--- |
+| Fixes Applied | {count} ({n} humans, {n} bots) |
+| Commits | {count} |
+| Verification | All gates passed |
+
+### Fix Summary
+| # | Priority | Reviewer | File:Line | Fix Applied | Commit |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+
+### Verification
+| Gate | Status |
+| :--- | :--- |
+| Lint / Type Check / Tests / Security / Build | Pass/Fail |
+
+**Next**: Wait for re-review. Bots re-analyze automatically on push.
+```
+
+---
+
+## Governance
+
+**PROHIBITED:** Modifying unrelated code · pushing without verification · dismissing comments without justification · force-pushing · omitting before/after diffs or reviewer attribution
+
+**REQUIRED:** Read ALL comments before fixing · priority-ordered fixing · atomic commits · full verification before push · detailed summary with attribution and file:line · re-request review
+
+---
+
+## Completion Criteria
+
+- [ ] All review comments fetched and attributed
+- [ ] Fix plan generated with priority ordering
+- [ ] Fixes implemented with before/after evidence
+- [ ] Verification pipeline passed
+- [ ] Summary comment posted with attribution and diffs
+- [ ] Re-review requested
+
+---
+
+## Related Resources
+
+- **Skill**: `.agent/skills/pr-toolkit/SKILL.md`
+- **Previous**: `/pr-review`
+- **Next**: Re-review cycle
+- **Related**: `/review` · `/pr`

package/.agent/workflows/pr-merge.md

@@ -0,0 +1,117 @@
+---
+description: Safe PR merge with dependency validation, CI verification, post-merge checks, and branch cleanup.
+version: 1.0.0
+sdlc-phase: ship
+skills: [pr-toolkit, verification-loop]
+commit-types: [feat, fix, refactor, perf, chore, docs, test]
+---
+
+# /pr-merge — Safe Pull Request Merge Workflow
+
+> **Trigger**: `/pr-merge <url>` · `/pr-merge #<number>`
+> **Lifecycle**: Ship — after review approval, before deployment
+
+> Standards: See `rules/workflow-standards.md`
+
+> [!CAUTION]
+> Merging modifies the target branch and is difficult to reverse. Ensure all checks pass, reviews approved, and dependencies merged.
+
+---
+
+## Critical Rules
+
+1. Never merge with failing CI checks
+2. Never merge without at least 1 approval (unless solo project)
+3. Never merge with unresolved `Depends-On:` PRs still open
+4. Verify merge target matches branch strategy
+5. Run post-merge validation for integration issues
+6. Prefer squash merge for features, merge commit for release/dev→main
+
+---
+
+## Argument Parsing
+
+| Command | Action |
+| :--- | :--- |
+| `/pr-merge #<number>` | Merge PR in current repo |
+| `/pr-merge #<number> --squash/--merge-commit/--rebase` | Force merge strategy |
+| `/pr-merge #<number> --dry-run` | Validate readiness without merging |
+
+---
+
+## Steps
+
+### Step 1: Validate PR State
+// turbo
+Verify PR is open, mergeable, not blocked via `gh pr view`.
+
+### Step 2: Verify Prerequisites
+// turbo
+- **Review**: `reviewDecision` must be `APPROVED`
+- **CI**: all checks passing via `gh pr checks`
+- **Dependencies**: extract `Depends-On` from body, verify all merged
+- **Branch strategy**: verify target matches detected strategy
+
+### Step 3: Execute Merge
+
+| Scenario | Default Strategy |
+| :--- | :--- |
+| Feature → dev | Squash merge |
+| dev → main (release) | Merge commit |
+| hotfix → main | Squash merge |
+
+```bash
+gh pr merge <number> --repo <owner/repo> --{squash|merge|rebase} --delete-branch
+```
+
+### Step 4: Post-Merge Validation
+// turbo
+- Verify merge recorded, check target branch CI
+- Notify dependent PRs that this dependency is now merged
+
+---
+
+## Output Template
+
+```markdown
+## PR Merged: #{number}
+
+| Field | Value |
+| :--- | :--- |
+| Merged into | {base} |
+| Strategy | {squash/merge/rebase} |
+| Branch cleanup | Deleted |
+
+### Post-Merge
+| Check | Status |
+| :--- | :--- |
+| CI on target | {status} |
+| Dependent PRs notified | {count} |
+
+**Next**: `/deploy` when ready
+```
+
+---
+
+## Governance
+
+**PROHIBITED:** Merging with failing CI · without approval · with open dependencies · force-merging past protections
+
+**REQUIRED:** All CI passing · review approval · dependency validation · branch strategy compliance · post-merge verification · branch cleanup
+
+---
+
+## Completion Criteria
+
+- [ ] PR validated (open, mergeable, approved, CI passing)
+- [ ] Dependencies verified, strategy compliance checked
+- [ ] Merged with appropriate strategy, branch deleted
+- [ ] Post-merge CI checked, dependent PRs notified
+
+---
+
+## Related Resources
+
+- **Skill**: `.agent/skills/pr-toolkit/SKILL.md`
+- **Previous**: `/pr-review` · `/pr-fix`
+- **Next**: `/deploy`

package/.agent/workflows/pr-review.md

@@ -0,0 +1,178 @@
+---
+description: Multi-perspective PR review covering hygiene, branch strategy, code quality, security, testing, and architecture. Engages with existing reviewer comments and tracks review rounds.
+version: 1.1.0
+sdlc-phase: verify
+skills: [pr-toolkit, verification-loop]
+commit-types: []
+---
+
+# /pr-review — Pull Request Review Workflow
+
+> **Trigger**: `/pr-review <url>` · `/pr-review <owner/repo>#<number>` · `/pr-review #<number>`
+> **Lifecycle**: Verify — peer review before merge
+
+> Standards: See `rules/workflow-standards.md` (artifact discipline, evidence standard, governance)
+
+> [!CAUTION]
+> This workflow posts reviews to GitHub visible to the entire team. Ensure findings are accurate, constructive, and properly prioritized.
+
+---
+
+## Critical Rules
+
+1. **EVIDENCE MANDATE** — every finding MUST include `file:line` reference with concrete fix suggestion. Generic statements are not findings. This applies globally to ALL steps below
+2. Fetch full PR diff before reviewing — never review from title/description alone
+3. Detect branch strategy before assessing target branch compliance
+4. Never post review with only NITs — if clean, APPROVE explicitly
+5. Never approve with known CRITICAL findings
+6. Engage with ALL existing reviews/comments (bots and humans) — acknowledge, challenge, or reference
+7. Track review rounds — for follow-ups, report which prior findings were addressed
+8. Review title: `PR #{number} Review — {content-specific summary}` (no agent branding)
+
+---
+
+## Argument Parsing
+
+| Command | Action |
+| :--- | :--- |
+| `/pr-review <url>` | Review PR at GitHub URL |
+| `/pr-review #<number>` | Review PR in current repo |
+| `/pr-review #<number> --local` | Review locally only — do not post |
+| `/pr-review #<number> --focus security` | Focus on security perspective only |
+
+---
+
+## Steps
+
+### Step 1: Parse PR Reference
+
+// turbo
+
+Extract `owner/repo` and PR number. Validate PR exists and is open via `gh pr view`.
+
+### Step 2: Fetch PR Data & Existing Comments
+
+```bash
+gh pr view <number> --repo <owner/repo> \
+  --json title,body,state,baseRefName,headRefName,author,files,additions,deletions,changedFiles,commits,labels,url,reviews,reviewRequests
+gh pr diff <number> --repo <owner/repo>
+gh api repos/<owner>/<repo>/pulls/<number>/reviews
+gh api repos/<owner>/<repo>/pulls/<number>/comments
+gh api repos/<owner>/<repo>/issues/<number>/comments
+gh pr checks <number> --repo <owner/repo>
+```
+
+### Step 3: Review Round & Existing Comment Analysis
+
+**3a. Round Detection**: Count prior substantive reviews. If Round N+1, cross-reference current diff against previous findings to track addressed vs unaddressed items.
+
+**3b. Existing Comment Engagement**: For each comment from any reviewer (human or bot):
+- Classify finding severity and assess validity
+- Valid + open → reference and build on it
+- Valid + addressed → acknowledge resolution
+- Invalid → challenge constructively with evidence
+- Duplicate of your finding → skip yours, reference theirs
+
+### Step 4: PR Hygiene
+
+// turbo
+
+- **Title**: conventional commits format, imperative mood, <72 chars
+- **Body**: Summary, Changes, Test Plan sections present
+- **Size**: XS/S/M/L/XL per pr-toolkit matrix. XL (50+ files/1500+ LOC) → CRITICAL (exception: automated vendor upgrades)
+- **Scope**: detect mixed concerns → HIGH
+
+### Step 5: Branch Strategy
+
+// turbo
+
+- Detect GitFlow vs Trunk-Based (check for `dev`/`develop` remote branch)
+- Validate target branch per strategy rules
+- Check branch naming convention
+
+### Step 6: Multi-Perspective Code Review
+
+Read each changed file. For every finding include: `file:line`, quoted code, impact explanation, concrete fix.
+
+**Cross-file consistency**: verify counts, references, categorizations match across related files.
+
+**6a. Code Quality** — function size (>50 lines), file size (>800 lines), nesting (>4 levels), error handling, debug artifacts, naming, immutability
+
+**6b. Security** — hardcoded secrets, input validation, injection risks, XSS, auth/authz, PII exposure
+
+**6c. Testing** — untested new code, coverage reduction, flaky patterns, missing edge cases
+
+**6d. Architecture** — pattern consistency, separation of concerns, circular deps, over-engineering, API consistency
+
+### Step 7: Generate Review Report
+
+1. Title: `PR #{number} Review — {2-5 word summary}`
+2. Round indicator with prior findings tracker (if Round 2+)
+3. Existing reviewer engagement summary
+4. **Group findings by severity** (CRITICAL → HIGH → MEDIUM → LOW → NIT) — mandatory
+5. "What's Good" section: 3+ specific positive observations with file paths
+6. Verdict per decision table
+
+### Step 8: Post Review to GitHub
+
+Skip if `--local`. Post via `gh pr review` with verdict. Post inline findings via `gh api`. Fallback to local display on failure.
+
+---
+
+## Output Template
+
+```markdown
+## PR #{number} Review — {summary}
+
+| Field | Value |
+| :--- | :--- |
+| PR | #{number} — {title} |
+| Branch | {head} → {base} |
+| Size | {label} ({files} files, +{add}/-{del}) |
+| Round | {Round N — X/Y prior findings addressed} |
+| Verdict | {APPROVE / REQUEST_CHANGES / COMMENT} |
+
+### Existing Reviewer Comments
+| Reviewer | Comments | Agreed | Challenged | Addressed |
+| :--- | :--- | :--- | :--- | :--- |
+
+### Assessment Summary
+| Perspective | Status | Findings |
+| :--- | :--- | :--- |
+| PR Hygiene / Branch / Code Quality / Security / Testing / Architecture | {status} | {count} |
+
+### Must Fix / High / Medium / Low
+{numbered findings with file:line, impact, fix suggestion}
+
+### What's Good
+- {3+ specific positive observations with file paths}
+
+## Verdict: {verdict} — {justification}
+```
+
+---
+
+## Governance
+
+**PROHIBITED:** Approving with CRITICAL findings · reviewing without full diff · findings without `file:line` · ignoring existing reviewer comments · agent branding in titles · severity-by-perspective grouping
+
+**REQUIRED:** Full diff analysis · concrete fix per finding · severity-first ordering · branch strategy detection · "What's Good" section · existing comment engagement · round tracking · cross-file consistency
+
+---
+
+## Completion Criteria
+
+- [ ] PR data, diff, and all existing comments fetched
+- [ ] Review round detected; existing comments analyzed
+- [ ] All 6 perspectives reviewed with file:line evidence
+- [ ] Findings grouped by severity with fix suggestions
+- [ ] "What's Good" section with 3+ observations
+- [ ] Verdict rendered and review posted (unless `--local`)
+
+---
+
+## Related Resources
+
+- **Skill**: `.agent/skills/pr-toolkit/SKILL.md`
+- **Agent**: `.agent/agents/pr-reviewer.md`
+- **Related**: `/pr` · `/pr-fix` · `/review`

package/.agent/workflows/pr-split.md

@@ -0,0 +1,118 @@
+---
+description: Guide splitting large PRs into focused sub-PRs by concern category with dependency-ordered merge plan.
+version: 1.0.0
+sdlc-phase: build
+skills: [pr-toolkit, git-workflow]
+commit-types: [chore]
+---
+
+# /pr-split — Pull Request Split Workflow
+
+> **Trigger**: `/pr-split` (current branch) · `/pr-split #<number>` (existing PR)
+> **Lifecycle**: Build — remediation for oversized PRs
+
+> Standards: See `rules/workflow-standards.md`
+
+> [!CAUTION]
+> Uses `git cherry-pick` and selective checkout — does NOT rewrite commits. Original branch preserved until user closes it.
+
+---
+
+## Critical Rules
+
+1. Never delete or force-push the original branch
+2. Analyze full diff before proposing split
+3. Each sub-PR must independently pass `/review`
+4. Include dependency ordering in split plan
+5. Use cherry-pick or selective checkout — preserve all commits
+6. Each sub-PR must be independently mergeable and testable
+
+---
+
+## Argument Parsing
+
+| Command | Action |
+| :--- | :--- |
+| `/pr-split` | Analyze current branch |
+| `/pr-split #<number>` | Analyze existing PR |
+| `/pr-split --dry-run` | Show plan only |
+| `/pr-split --auto` | Auto-split by file category |
+
+---
+
+## Steps
+
+### Step 1: Analyze Diff
+// turbo
+Classify PR size. If XS/S/M → **STOP** (splitting not needed). If L/XL → proceed.
+
+### Step 2: Categorize Files
+// turbo
+Group changed files by concern: Feature Code, Tests, Configuration, Dependencies, Documentation.
+
+### Step 3: Propose Split Plan
+// turbo
+Generate plan with merge ordering. Present for user approval. If `--dry-run` → **STOP**.
+
+```markdown
+| # | Sub-PR | Branch | Files | Type | Depends On |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+```
+
+### Step 4: Create Sub-Branches
+For each sub-PR: checkout target, create `split/<original>-<category>`, selectively checkout files from original branch, commit.
+
+### Step 5: Verify Each Sub-Branch
+// turbo
+Run `/review` pipeline per sub-branch. Each must independently build and test.
+
+### Step 6: Create Sub-PRs
+Follow `/pr` workflow for each sub-PR. Include in body: split context, dependency declarations, merge order.
+
+### Step 7: Update Original PR
+Post comment linking all sub-PRs with merge order.
+
+---
+
+## Output Template
+
+```markdown
+## PR Split Complete
+
+| Field | Value |
+| :--- | :--- |
+| Original | #{number} |
+| Sub-PRs | {count} |
+| Verification | All pass /review |
+
+### Sub-PRs
+| # | PR | Title | Size | Status |
+
+**Next**: Review and merge in order.
+```
+
+---
+
+## Governance
+
+**PROHIBITED:** Deleting original branch · sub-PRs that can't build independently · circular dependencies · proceeding without user approval
+
+**REQUIRED:** Full diff analysis · user approval of plan · each sub-PR passes `/review` · dependency ordering · original PR updated with links
+
+---
+
+## Completion Criteria
+
+- [ ] PR analyzed, files categorized
+- [ ] Split plan approved by user
+- [ ] Sub-branches created and verified
+- [ ] Sub-PRs created with dependency declarations
+- [ ] Original PR updated
+
+---
+
+## Related Resources
+
+- **Skill**: `.agent/skills/pr-toolkit/SKILL.md`
+- **Previous**: `/pr` (XL warning triggered)
+- **Next**: `/pr-review` · `/pr-merge`