@kody-ade/engine 0.1.0

package/templates/kody.yml

@@ -0,0 +1,450 @@
+name: kody
+
+on:
+  workflow_dispatch:
+    inputs:
+      task_id:
+        required: true
+        type: string
+      mode:
+        type: string
+        default: "full"
+      from_stage:
+        type: string
+        default: ""
+      issue_number:
+        type: string
+        default: ""
+      feedback:
+        type: string
+        default: ""
+      dry_run:
+        type: boolean
+        default: false
+
+  issue_comment:
+    types: [created]
+
+  pull_request:
+    types: [closed]
+
+  pull_request_review:
+    types: [submitted]
+
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+
+  push:
+    branches: [main, dev]
+    paths: ["src/**", "kody.config.json", "package.json"]
+
+concurrency:
+  group: kody-${{ github.event.inputs.task_id || github.event.issue.number || github.event.pull_request.number || github.event.workflow_run.id || github.sha }}
+  cancel-in-progress: false
+
+permissions:
+  issues: write
+  pull-requests: write
+  contents: write
+
+jobs:
+  # ─── Parse (issue_comment trigger only) ──────────────────────────────────────
+  parse:
+    if: >-
+      github.event_name == 'issue_comment' &&
+      (contains(github.event.comment.body, '@kody') || contains(github.event.comment.body, '/kody'))
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    outputs:
+      task_id: ${{ steps.parse.outputs.task_id }}
+      mode: ${{ steps.parse.outputs.mode }}
+      from_stage: ${{ steps.parse.outputs.from_stage }}
+      issue_number: ${{ steps.parse.outputs.issue_number }}
+      pr_number: ${{ steps.parse.outputs.pr_number }}
+      feedback: ${{ steps.parse.outputs.feedback }}
+      ci_run_id: ${{ steps.parse.outputs.ci_run_id }}
+      ticket_id: ${{ steps.parse.outputs.ticket_id }}
+      prd_file: ${{ steps.parse.outputs.prd_file }}
+      dry_run: ${{ steps.parse.outputs.dry_run }}
+      valid: ${{ steps.parse.outputs.valid }}
+    steps:
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install Kody Engine
+        run: npm install -g @kody-ade/kody-engine-lite
+
+      - name: Validate author
+        id: safety
+        run: |
+          ALLOWED="COLLABORATOR MEMBER OWNER"
+          ASSOC="${{ github.event.comment.author_association }}"
+          if echo "$ALLOWED" | grep -qw "$ASSOC"; then
+            echo "valid=true" >> $GITHUB_OUTPUT
+          else
+            echo "valid=false" >> $GITHUB_OUTPUT
+            echo "reason=Author association '$ASSOC' not allowed" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Add reaction
+        if: steps.safety.outputs.valid == 'true'
+        uses: actions/github-script@v7
+        continue-on-error: true
+        with:
+          script: |
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes'
+            })
+
+      - name: Parse inputs
+        if: steps.safety.outputs.valid == 'true'
+        id: parse
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+          ISSUE_NUMBER: ${{ github.event.issue.number }}
+          ISSUE_IS_PR: ${{ github.event.issue.pull_request && 'true' || '' }}
+          TRIGGER_TYPE: comment
+        run: kody-engine-lite ci-parse
+
+  # ─── Orchestrate ─────────────────────────────────────────────────────────────
+  orchestrate:
+    if: >-
+      github.event_name == 'workflow_dispatch' ||
+      (needs.parse.result == 'success' && needs.parse.outputs.valid == 'true') ||
+      (github.event_name == 'pull_request_review' && github.event.review.state == 'changes_requested')
+    needs: [parse]
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    steps:
+      - name: Generate App token
+        id: app-token
+        if: vars.KODY_APP_ID != ''
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.KODY_APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          repositories: ${{ github.event.repository.name }}
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          persist-credentials: true
+          token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+
+      - name: Checkout PR branch (for fix/rerun/review on PRs)
+        if: github.event.issue.pull_request && (needs.parse.outputs.mode == 'fix' || needs.parse.outputs.mode == 'fix-ci' || needs.parse.outputs.mode == 'rerun' || needs.parse.outputs.mode == 'review' || needs.parse.outputs.mode == 'resolve')
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+        run: |
+          PR_NUM="${{ github.event.issue.number }}"
+          PR_BRANCH=$(gh pr view "$PR_NUM" --json headRefName -q '.headRefName')
+          echo "Checking out PR branch: $PR_BRANCH"
+          git checkout "$PR_BRANCH"
+          git pull origin "$PR_BRANCH"
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Install Claude Code CLI
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Install LiteLLM proxy
+        run: pip install 'litellm[proxy]' prisma && python -m prisma py fetch
+
+      - name: Configure git
+        run: |
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git config user.name "github-actions[bot]"
+
+      - name: Export project secrets
+        env:
+          ALL_SECRETS: ${{ toJSON(secrets) }}
+        run: |
+          echo "$ALL_SECRETS" | jq -r 'to_entries[] | select(.key | test("^(GITHUB_TOKEN)$") | not) | @json' | while IFS= read -r entry; do
+            KEY=$(echo "$entry" | jq -r '.key')
+            VALUE=$(echo "$entry" | jq -r '.value')
+            DELIM="KODY_EOF_${KEY}"
+            echo "${KEY}<<${DELIM}" >> $GITHUB_ENV
+            echo "${VALUE}" >> $GITHUB_ENV
+            echo "${DELIM}" >> $GITHUB_ENV
+          done
+
+      - name: Warm up Next.js build cache
+        continue-on-error: true
+        run: npx next build 2>/dev/null || true
+        timeout-minutes: 15
+
+      - name: Run Kody pipeline
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+          TASK_ID: ${{ github.event.inputs.task_id || needs.parse.outputs.task_id }}
+          MODE: ${{ github.event.inputs.mode || needs.parse.outputs.mode || 'full' }}
+          FROM_STAGE: ${{ github.event.inputs.from_stage || needs.parse.outputs.from_stage }}
+          ISSUE_NUMBER: ${{ github.event.inputs.issue_number || needs.parse.outputs.issue_number }}
+          PR_NUMBER: ${{ needs.parse.outputs.pr_number }}
+          FEEDBACK: ${{ github.event.inputs.feedback || needs.parse.outputs.feedback }}
+          COMPLEXITY: ${{ needs.parse.outputs.complexity }}
+          CI_RUN_ID: ${{ needs.parse.outputs.ci_run_id }}
+          TICKET_ID: ${{ needs.parse.outputs.ticket_id }}
+          PRD_FILE: ${{ needs.parse.outputs.prd_file }}
+          DRY_RUN: ${{ github.event.inputs.dry_run || needs.parse.outputs.dry_run || 'false' }}
+          RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
+        run: |
+          if [ "$MODE" = "bootstrap" ]; then
+            echo "Running bootstrap..."
+            npx kody-engine-lite bootstrap
+          elif [ "$MODE" = "taskify" ]; then
+            echo "Running taskify..."
+            ARGS=""
+            [ -n "$TICKET_ID" ] && ARGS="$ARGS --ticket $TICKET_ID"
+            [ -n "$PRD_FILE" ] && ARGS="$ARGS --file $PRD_FILE"
+            [ -n "$ISSUE_NUMBER" ] && ARGS="$ARGS --issue-number $ISSUE_NUMBER"
+            [ -n "$TASK_ID" ] && ARGS="$ARGS --task-id $TASK_ID"
+            npx kody-engine-lite taskify $ARGS
+          else
+            CMD="run"
+            [ "$MODE" = "rerun" ] && CMD="rerun"
+            [ "$MODE" = "fix" ] && CMD="fix"
+            [ "$MODE" = "fix-ci" ] && CMD="fix-ci"
+            [ "$MODE" = "review" ] && CMD="review"
+            [ "$MODE" = "resolve" ] && CMD="resolve"
+            [ "$MODE" = "status" ] && CMD="status"
+            ARGS="--issue-number $ISSUE_NUMBER"
+            [ -n "$TASK_ID" ] && ARGS="$ARGS --task-id $TASK_ID"
+            [ -n "$PR_NUMBER" ] && ARGS="$ARGS --pr-number $PR_NUMBER"
+            [ -n "$FROM_STAGE" ] && ARGS="$ARGS --from $FROM_STAGE"
+            [ -n "$COMPLEXITY" ] && ARGS="$ARGS --complexity $COMPLEXITY"
+            # FEEDBACK is also passed via env var (avoids shell escaping issues)
+            [ -n "$FEEDBACK" ] && ARGS="$ARGS --feedback \"$FEEDBACK\""
+            [ "$DRY_RUN" = "true" ] && ARGS="$ARGS --dry-run"
+            npx kody-engine-lite $CMD $ARGS
+          fi
+
+      - name: Pipeline summary
+        if: always()
+        run: |
+          TASK_ID="${{ github.event.inputs.task_id || needs.parse.outputs.task_id }}"
+          STATUS_FILE=".kody/tasks/${TASK_ID}/status.json"
+          if [ -f "$STATUS_FILE" ]; then
+            STATE=$(jq -r '.state' "$STATUS_FILE")
+            ICON="❌"
+            [ "$STATE" = "completed" ] && ICON="✅"
+            echo "## ${ICON} Kody Pipeline: \`${TASK_ID}\`" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "**Status:** ${STATE}" >> $GITHUB_STEP_SUMMARY
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "| Stage | State |" >> $GITHUB_STEP_SUMMARY
+            echo "|-------|-------|" >> $GITHUB_STEP_SUMMARY
+            for stage in taskify plan build verify review review-fix ship; do
+              SSTATE=$(jq -r ".stages[\"$stage\"].state // \"—\"" "$STATUS_FILE")
+              case "$SSTATE" in
+                completed) SICON="✅" ;;
+                failed)    SICON="❌" ;;
+                timeout)   SICON="⏱" ;;
+                running)   SICON="▶️" ;;
+                *)         SICON="○" ;;
+              esac
+              echo "| ${stage} | ${SICON} ${SSTATE} |" >> $GITHUB_STEP_SUMMARY
+            done
+          fi
+
+      - name: Upload artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        continue-on-error: true
+        with:
+          name: kody-tasks-${{ github.event.inputs.task_id || needs.parse.outputs.task_id }}
+          path: .kody/tasks/
+          retention-days: 3
+
+  # ─── Close Issue on PR Merge ────────────────────────────────────────────────
+  close-issue-on-merge:
+    if: >-
+      github.event_name == 'pull_request' &&
+      github.event.pull_request.merged == true
+    runs-on: ubuntu-latest
+    permissions:
+      issues: write
+    steps:
+      - name: Generate App token
+        id: app-token
+        if: vars.KODY_APP_ID != ''
+        uses: actions/create-github-app-token@v1
+        with:
+          app-id: ${{ vars.KODY_APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          repositories: ${{ github.event.repository.name }}
+
+      - name: Close linked issue
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ steps.app-token.outputs.token || secrets.GITHUB_TOKEN }}
+          script: |
+            // Extract issue number from branch name (e.g. "42--feature-name")
+            const branch = context.payload.pull_request.head.ref;
+            const match = branch.match(/^(\d+)--/);
+            if (!match) return;
+            const issueNumber = parseInt(match[1], 10);
+
+            // Verify the issue exists and is open
+            try {
+              const { data: issue } = await github.rest.issues.get({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+              });
+              if (issue.state === 'closed') return;
+              if (issue.pull_request) return; // Skip if it's a PR, not an issue
+
+              await github.rest.issues.update({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+                state: 'closed',
+                state_reason: 'completed',
+              });
+              core.info(`Closed issue #${issueNumber} after PR #${context.payload.pull_request.number} was merged`);
+            } catch (e) {
+              core.warning(`Could not close issue #${issueNumber}: ${e.message}`);
+            }
+
+  # ─── Error Notifications ─────────────────────────────────────────────────────
+  notify-parse-error:
+    if: >-
+      github.event_name == 'issue_comment' &&
+      needs.parse.outputs.valid != 'true' &&
+      (contains(github.event.comment.body, '@kody') || contains(github.event.comment.body, '/kody'))
+    needs: [parse]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+              body: '❌ Failed to parse command.\n\nUsage: `@kody [full|rerun|status] <task-id> [--from <stage>] [--feedback "<text>"]`'
+            })
+
+  notify-orchestrate-error:
+    if: failure() && needs.orchestrate.result == 'failure'
+    needs: [orchestrate]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/github-script@v7
+        with:
+          script: |
+            const issueNumber = Number('${{ github.event.inputs.issue_number || needs.parse.outputs.issue_number || 0 }}');
+            if (issueNumber > 0) {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: issueNumber,
+                body: `❌ Pipeline failed. [View logs](${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${context.runId})`
+              });
+            }
+
+  # ─── Fix-CI Auto-trigger (workflow_run trigger) ─────────────────────────────
+  fix-ci-trigger:
+    if: >-
+      github.event_name == 'workflow_run' &&
+      github.event.workflow_run.conclusion == 'failure' &&
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.pull_requests[0]
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    permissions:
+      issues: write
+      pull-requests: write
+    steps:
+      - name: Check loop guard and post fix-ci comment
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = context.payload.workflow_run.pull_requests[0];
+            const prNumber = pr.number;
+
+            // Check recent comments for existing fix-ci attempt (last 24h)
+            const comments = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              per_page: 30,
+            });
+
+            const oneDayAgo = new Date(Date.now() - 24 * 60 * 60 * 1000);
+            const recentFixCi = comments.data.filter(
+              (c) => c.body.includes('@kody fix-ci') && new Date(c.created_at) > oneDayAgo
+            );
+
+            if (recentFixCi.length >= 1) {
+              core.info('Loop guard: @kody fix-ci already commented in last 24h, skipping');
+              return;
+            }
+
+            // Check if last commit was from a bot (kody's previous fix attempt)
+            const commits = await github.rest.pulls.listCommits({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: prNumber,
+              per_page: 1,
+            });
+            const lastAuthor = commits.data[commits.data.length - 1]?.commit?.author?.name;
+            if (lastAuthor === 'github-actions[bot]' || lastAuthor === 'kody[bot]') {
+              core.info('Loop guard: last commit from bot, skipping');
+              return;
+            }
+
+            // Post fix-ci comment
+            const runId = context.payload.workflow_run.id;
+            const runUrl = `${context.serverUrl}/${context.repo.owner}/${context.repo.repo}/actions/runs/${runId}`;
+            await github.rest.issues.createComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: prNumber,
+              body: `@kody fix-ci\nCI failed: [View logs](${runUrl})\nRun ID: ${runId}`,
+            });
+            core.info(`Posted @kody fix-ci on PR #${prNumber} for run ${runId}`);
+
+  # ─── Smoke Test (push trigger) ──────────────────────────────────────────────
+  smoke-test:
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+        with:
+          version: latest
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Typecheck
+        run: pnpm tsc --noEmit
+      - name: CLI loads
+        run: npx kody-engine-lite --help
+      - name: Dry run
+        run: |
+          mkdir -p .kody/tasks/smoke-test
+          echo "Smoke test task" > .kody/tasks/smoke-test/task.md
+          npx kody-engine-lite run --task-id smoke-test --dry-run || true
+          if [ -f ".kody/tasks/smoke-test/status.json" ]; then
+            echo "✓ status.json created"
+            cat .kody/tasks/smoke-test/status.json
+          fi
+          rm -rf .kody/tasks/smoke-test

package/templates/watch-agents/branch-cleanup/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "branch-cleanup",
+  "description": "Finds stale remote branches with no recent activity and suggests cleanup",
+  "schedule": {
+    "every": 96
+  }
+}

package/templates/watch-agents/branch-cleanup/agent.md

@@ -0,0 +1,13 @@
+List remote branches and identify stale ones that should be cleaned up.
+
+1. Run `gh api repos/{{repo}}/branches --paginate --jq '.[] | {name: .name, protected: .protected}'` to get all branches.
+2. For each non-protected branch, check its last commit date using `gh api repos/{{repo}}/commits?sha=BRANCH_NAME&per_page=1 --jq '.[0].commit.committer.date'`.
+3. Flag any branch whose last commit is **older than 30 days**.
+4. Ignore these branches: `main`, `dev`, `staging`, `production`, and any branch starting with `release/`.
+5. Check if there is already an open issue with label `kody:watch:stale-branches` — if so, do NOT create a new one.
+6. If stale branches are found, create **one** GitHub issue:
+   - Title: `Branch cleanup: N stale branches older than 30 days`
+   - Label: `kody:watch:stale-branches`
+   - Body: a markdown table with columns: Branch Name, Last Commit Date, Days Stale. End with the command to delete them: `git push origin --delete branch-name`.
+
+If no stale branches are found, do not create an issue.

package/templates/watch-agents/dependency-checker/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "dependency-checker",
+  "description": "Checks for outdated or vulnerable dependencies and creates tracking issues",
+  "schedule": {
+    "every": 96
+  }
+}

package/templates/watch-agents/dependency-checker/agent.md

@@ -0,0 +1,14 @@
+Audit the repository's dependencies for known vulnerabilities.
+
+1. Read `package.json` to understand the project's dependency stack.
+2. Run `npm audit --json` (or `pnpm audit --json` if pnpm-lock.yaml exists) to check for known vulnerabilities.
+3. Focus only on **high** and **critical** severity vulnerabilities.
+
+For each finding:
+1. Check if there is already an open issue with label `kody:watch:vulnerability` mentioning the package name. If so, skip it.
+2. Create a GitHub issue with:
+   - Title: `Vulnerability: <package-name> (<severity>)`
+   - Label: `kody:watch:vulnerability`
+   - Body containing: package name, current version, severity, advisory URL (if available), and suggested fix (upgrade command)
+
+If no high/critical vulnerabilities are found, do not create any issues.

package/templates/watch-agents/readme-health/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "readme-health",
+  "description": "Checks if README.md exists and documents essential sections",
+  "schedule": {
+    "every": 96
+  }
+}

package/templates/watch-agents/readme-health/agent.md

@@ -0,0 +1,17 @@
+Check the repository's README.md for completeness and essential documentation.
+
+1. Read `README.md` from the repository root. If it does not exist, that is a critical finding.
+2. Check for the presence of these essential sections (look for headings or keywords):
+   - **Project description** — what the project does (first paragraph or a "## About" section)
+   - **Getting started / Installation** — how to install and set up
+   - **Usage / Running** — how to run the project (e.g. dev server, scripts)
+   - **Environment variables** — required env vars or reference to .env.example
+   - **Tech stack** — frameworks, languages, databases used
+3. Also read `package.json` to understand what scripts are available and cross-reference with the README.
+4. Check if there is already an open issue with label `kody:watch:readme-health` — if so, do NOT create a new one.
+5. If any essential sections are missing, create **one** GitHub issue:
+   - Title: `README health: N missing sections`
+   - Label: `kody:watch:readme-health`
+   - Body: list which sections are present (with a checkmark) and which are missing, with a brief suggestion for each missing section.
+
+If README is complete with all essential sections, do not create an issue.

package/templates/watch-agents/stale-pr-reviewer/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "stale-pr-reviewer",
+  "description": "Finds pull requests with no recent activity and creates tracking issues",
+  "schedule": {
+    "every": 48
+  }
+}

package/templates/watch-agents/stale-pr-reviewer/agent.md

@@ -0,0 +1,13 @@
+List all open pull requests. For each PR, check the last activity date (most recent of: last commit, last comment, last review).
+
+Flag any PR that has had **no activity in the last 7 days** as stale.
+
+For each stale PR:
+1. First, check if there is already an open issue with the label `kody:watch:stale-pr` that mentions this PR number. If so, skip it.
+2. Create a GitHub issue with:
+   - Title: `Stale PR #<number>: <pr-title>`
+   - Label: `kody:watch:stale-pr`
+   - Body containing: PR number, author, days since last activity, a link to the PR, and a suggested action (ping author, close, or merge)
+
+Ignore PRs that have any of these labels: `on-hold`, `wip`, `draft`.
+Do not flag draft PRs.

package/templates/watch-agents/todo-scanner/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "todo-scanner",
+  "description": "Scans source code for TODO, FIXME, and HACK comments and creates tracking issues",
+  "schedule": {
+    "every": 48
+  }
+}

package/templates/watch-agents/todo-scanner/agent.md

@@ -0,0 +1,10 @@
+Scan the repository source code for TODO, FIXME, and HACK comments that indicate unfinished work or known issues.
+
+1. Use `grep -rn "TODO\|FIXME\|HACK\|XXX" src/ --include="*.ts" --include="*.tsx"` to find all markers.
+2. Group findings by type (TODO, FIXME, HACK).
+3. Check if there is already an open issue with label `kody:watch:todo-scan` — if so, do NOT create a new one.
+4. If no existing issue, create **one** GitHub issue summarizing all findings:
+   - Title: `Code health: N unresolved TODO/FIXME/HACK markers found`
+   - Label: `kody:watch:todo-scan`
+   - Body: a markdown table with columns: Type, File, Line, Comment text
+   - End with a brief recommendation to address high-priority items (FIXME, HACK) first.