first-tree 0.0.2 → 0.0.3

package/skills/first-tree/assets/framework/workflows/pr-review.yml

@@ -0,0 +1,146 @@
+name: PR Review
+
+on:
+  pull_request:
+    types: [opened, reopened, synchronize]
+  issue_comment:
+    types: [created]
+
+jobs:
+  review:
+    if: >
+      github.event_name == 'pull_request' ||
+      (github.event_name == 'issue_comment' &&
+       github.event.issue.pull_request &&
+       contains(github.event.comment.body, '@claude'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pull-requests: write
+      issues: write
+    env:
+      ANTHROPIC_BASE_URL: "https://openrouter.ai/api"
+      ANTHROPIC_AUTH_TOKEN: ${{ secrets.OPENROUTER_API_KEY }}
+      ANTHROPIC_API_KEY: ""
+      ANTHROPIC_DEFAULT_SONNET_MODEL: "anthropic/claude-sonnet-4.6"
+      GH_TOKEN: ${{ github.token }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install Claude Code
+        run: curl -fsSL https://claude.ai/install.sh | bash
+
+      - name: Get PR info
+        id: pr
+        run: |
+          PR_NUMBER=${{ github.event.pull_request.number || github.event.issue.number }}
+          echo "number=$PR_NUMBER" >> "$GITHUB_OUTPUT"
+          gh pr diff "$PR_NUMBER" > /tmp/pr-diff.txt
+          gh pr view "$PR_NUMBER" --json headRefOid -q .headRefOid > /tmp/pr-head-sha.txt
+
+      - name: Run Claude review
+        run: npx tsx skills/first-tree/assets/framework/helpers/run-review.ts
+
+      - name: Parse and post review
+        run: |
+          PR_NUMBER=${{ steps.pr.outputs.number }}
+          HEAD_SHA=$(cat /tmp/pr-head-sha.txt)
+
+          # Extract fields
+          VERDICT=$(jq -r '.verdict // "COMMENT"' /tmp/review.json)
+          SUMMARY=$(jq -r '.summary // "Review completed."' /tmp/review.json)
+
+          case "$VERDICT" in
+            APPROVE) EVENT="APPROVE" ;;
+            REQUEST_CHANGES) EVENT="REQUEST_CHANGES" ;;
+            *) EVENT="COMMENT" ;;
+          esac
+
+          BODY="${SUMMARY}
+
+          ---
+          *Automated review by Claude Code via OpenRouter*"
+
+          # Check for inline comments
+          HAS_COMMENTS=$(jq 'has("inline_comments") and (.inline_comments | length > 0)' /tmp/review.json)
+
+          if [ "$HAS_COMMENTS" != "true" ]; then
+            gh api \
+              "repos/${{ github.repository }}/pulls/${PR_NUMBER}/reviews" \
+              -f body="$BODY" \
+              -f event="$EVENT" \
+              -f commit_id="$HEAD_SHA"
+          else
+            # Transform inline_comments to GitHub API format (file->path, comment->body)
+            jq '[.inline_comments[] | {path: .file, line: .line, body: .comment}]' \
+              /tmp/review.json > /tmp/comments.json
+
+            jq -n \
+              --arg body "$BODY" \
+              --arg event "$EVENT" \
+              --arg sha "$HEAD_SHA" \
+              --slurpfile comments /tmp/comments.json \
+              '{
+                body: $body,
+                event: $event,
+                commit_id: $sha,
+                comments: $comments[0]
+              }' > /tmp/review-payload.json
+
+            # Try inline review; fall back to summary-only if lines can't be resolved
+            if ! gh api \
+              "repos/${{ github.repository }}/pulls/${PR_NUMBER}/reviews" \
+              --input /tmp/review-payload.json 2>/tmp/review-api-error.txt; then
+              echo "Inline review failed, falling back to summary-only review"
+              cat /tmp/review-api-error.txt
+              INLINE_TEXT=$(jq -r '.[] | "**\(.path):\(.line)** — \(.body)"' /tmp/comments.json)
+              FALLBACK_BODY="${SUMMARY}
+
+          ### Inline Comments
+
+          ${INLINE_TEXT}
+
+          ---
+          *Automated review by Claude Code via OpenRouter*"
+              gh api \
+                "repos/${{ github.repository }}/pulls/${PR_NUMBER}/reviews" \
+                -f body="$FALLBACK_BODY" \
+                -f event="$EVENT" \
+                -f commit_id="$HEAD_SHA"
+            fi
+          fi
+
+      - name: Post full review output as comment
+        if: always()
+        run: |
+          PR_NUMBER=${{ steps.pr.outputs.number }}
+          {
+            echo "## Claude Code Review Output"
+            echo ""
+            if [ -f /tmp/review.json ] && jq empty /tmp/review.json 2>/dev/null; then
+              VERDICT=$(jq -r '.verdict // "N/A"' /tmp/review.json)
+              SUMMARY=$(jq -r '.summary // "N/A"' /tmp/review.json)
+              echo "**Verdict:** ${VERDICT}"
+              echo ""
+              echo "**Summary:** ${SUMMARY}"
+              HAS_COMMENTS=$(jq 'has("inline_comments") and (.inline_comments | length > 0)' /tmp/review.json)
+              if [ "$HAS_COMMENTS" = "true" ]; then
+                echo ""
+                echo "### Inline Comments"
+                echo ""
+                jq -r '.inline_comments[] | "#### \(.file):\(.line)\n\(.comment)\n"' /tmp/review.json
+              fi
+            else
+              echo "*No review output produced or failed to parse.*"
+            fi
+            echo ""
+            echo "---"
+            echo "*Automated review by Claude Code via OpenRouter*"
+          } > /tmp/comment-body.md
+          gh pr comment "$PR_NUMBER" --body-file /tmp/comment-body.md

package/skills/first-tree/assets/framework/workflows/validate.yml

@@ -0,0 +1,19 @@
+name: Validate Tree
+
+on:
+  pull_request:
+    paths:
+      - "**/*.md"
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Validate tree
+        run: npx -p first-tree context-tree verify

package/skills/first-tree/engine/commands/help.ts

@@ -0,0 +1,32 @@
+const HELP_USAGE = `usage: context-tree help <topic>
+
+Topics:
+  onboarding   How to set up a context tree from scratch
+`;
+
+export { HELP_USAGE };
+
+type Output = (text: string) => void;
+
+export async function runHelp(
+  args: string[],
+  output: Output = console.log,
+): Promise<number> {
+  const topic = args[0];
+
+  if (!topic || topic === "--help" || topic === "-h") {
+    output(HELP_USAGE);
+    return 0;
+  }
+
+  switch (topic) {
+    case "onboarding": {
+      const { runOnboarding } = await import("#skill/engine/onboarding.js");
+      return runOnboarding(output);
+    }
+    default:
+      output(`Unknown help topic: ${topic}`);
+      output(HELP_USAGE);
+      return 1;
+  }
+}

package/skills/first-tree/engine/commands/init.ts

@@ -0,0 +1 @@
+export * from "#skill/engine/init.js";

package/skills/first-tree/engine/commands/upgrade.ts

@@ -0,0 +1 @@
+export * from "#skill/engine/upgrade.js";

package/skills/first-tree/engine/commands/verify.ts

@@ -0,0 +1 @@
+export * from "#skill/engine/verify.js";

package/skills/first-tree/engine/init.ts

@@ -0,0 +1,145 @@
+import {
+  existsSync,
+  mkdirSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { Repo } from "#skill/engine/repo.js";
+import { ONBOARDING_TEXT } from "#skill/engine/onboarding.js";
+import { evaluateAll } from "#skill/engine/rules/index.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import {
+  copyCanonicalSkill,
+  renderTemplateFile,
+  resolveBundledPackageRoot,
+} from "#skill/engine/runtime/installer.js";
+import {
+  FRAMEWORK_ASSET_ROOT,
+  FRAMEWORK_VERSION,
+  INSTALLED_PROGRESS,
+} from "#skill/engine/runtime/asset-loader.js";
+
+/**
+ * The interactive prompt tool the agent should use to present choices.
+ * Different agents may name this differently — change it here to update
+ * all generated task text at once.
+ */
+export const INTERACTIVE_TOOL = "AskUserQuestion";
+
+const TEMPLATE_MAP: [string, string][] = [
+  ["root-node.md.template", "NODE.md"],
+  ["agent.md.template", "AGENT.md"],
+  ["members-domain.md.template", "members/NODE.md"],
+];
+
+function installSkill(source: string, target: string): void {
+  copyCanonicalSkill(source, target);
+  console.log(
+    "  Installed skills/first-tree/ from the bundled first-tree package",
+  );
+}
+
+function renderTemplates(target: string): void {
+  const frameworkDir = join(target, FRAMEWORK_ASSET_ROOT);
+  for (const [templateName, targetPath] of TEMPLATE_MAP) {
+    if (existsSync(join(target, targetPath))) {
+      console.log(`  Skipped ${targetPath} (already exists)`);
+    } else if (renderTemplateFile(frameworkDir, templateName, target, targetPath)) {
+      console.log(`  Created ${targetPath}`);
+    }
+  }
+}
+
+export function formatTaskList(groups: RuleResult[]): string {
+  const lines: string[] = [
+    "# Context Tree Init\n",
+    "**Agent instructions:** Before starting work, analyze the full task list below and" +
+      " identify all information you need from the user. Ask the user for their code" +
+      " repositories or project directories so you can analyze the source yourself —" +
+      " derive project descriptions, domains, and members from the code instead of" +
+      " asking the user to describe them. Collect everything upfront using the" +
+      ` **${INTERACTIVE_TOOL}** tool with structured options — present selectable choices` +
+      " (with label and description) so the user can pick instead of typing free-form" +
+      ` answers. You may batch up to 4 questions per ${INTERACTIVE_TOOL} call.\n`,
+  ];
+  for (const group of groups) {
+    lines.push(`## ${group.group}`);
+    for (const task of group.tasks) {
+      lines.push(`- [ ] ${task}`);
+    }
+    lines.push("");
+  }
+  lines.push("## Verification");
+  lines.push(
+    "After completing the tasks above, run `context-tree verify` to confirm:",
+  );
+  lines.push(`- [ ] \`${FRAMEWORK_VERSION}\` exists`);
+  lines.push("- [ ] Root NODE.md has valid frontmatter (title, owners)");
+  lines.push("- [ ] AGENT.md exists with framework markers");
+  lines.push("- [ ] `context-tree verify` passes with no errors");
+  lines.push("- [ ] At least one member node exists");
+  lines.push("");
+  lines.push("---");
+  lines.push("");
+  lines.push(
+    "**Important:** As you complete each task, check it off in" +
+      ` \`${INSTALLED_PROGRESS}\` by changing \`- [ ]\` to \`- [x]\`.` +
+      " Run `context-tree verify` when done — it will fail if any" +
+      " items remain unchecked.",
+  );
+  lines.push("");
+  return lines.join("\n");
+}
+
+export function writeProgress(repo: Repo, content: string): void {
+  const progressPath = join(repo.root, repo.preferredProgressPath());
+  mkdirSync(dirname(progressPath), { recursive: true });
+  writeFileSync(progressPath, content);
+}
+
+export interface InitOptions {
+  sourceRoot?: string;
+}
+
+export function runInit(repo?: Repo, options?: InitOptions): number {
+  const r = repo ?? new Repo();
+
+  if (!r.isGitRepo()) {
+    console.error(
+      "Error: not a git repository. Initialize one first:\n  git init",
+    );
+    return 1;
+  }
+
+  if (!r.hasFramework()) {
+    try {
+      const sourceRoot = options?.sourceRoot ?? resolveBundledPackageRoot();
+      console.log(
+        "Installing the framework skill bundled with this first-tree package...",
+      );
+      console.log("Installing skill and scaffolding...");
+      installSkill(sourceRoot, r.root);
+      renderTemplates(r.root);
+      console.log();
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "unknown error";
+      console.error(`Error: ${message}`);
+      return 1;
+    }
+  }
+
+  console.log(ONBOARDING_TEXT);
+  console.log("---\n");
+
+  const groups = evaluateAll(r);
+  if (groups.length === 0) {
+    console.log("All checks passed. Your context tree is set up.");
+    return 0;
+  }
+
+  const output = formatTaskList(groups);
+  console.log(output);
+  writeProgress(r, output);
+  console.log(`Progress file written to ${r.preferredProgressPath()}`);
+  return 0;
+}

package/skills/first-tree/engine/onboarding.ts

@@ -0,0 +1,10 @@
+import ONBOARDING_TEXT from "#skill/references/onboarding.md";
+
+export { ONBOARDING_TEXT };
+
+type Output = (text: string) => void;
+
+export function runOnboarding(output: Output = console.log): number {
+  output(ONBOARDING_TEXT);
+  return 0;
+}

package/skills/first-tree/engine/repo.ts

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join, resolve } from "node:path";
+import {
+  FRAMEWORK_VERSION,
+  LEGACY_SKILL_PROGRESS,
+  LEGACY_SKILL_VERSION,
+  LEGACY_PROGRESS,
+  LEGACY_VERSION,
+  INSTALLED_PROGRESS,
+  type FrameworkLayout,
+  detectFrameworkLayout,
+  frameworkVersionCandidates,
+  progressFileCandidates,
+  resolveFirstExistingPath,
+} from "#skill/engine/runtime/asset-loader.js";
+
+const FRONTMATTER_RE = /^---\s*\n(.*?)\n---/s;
+const OWNERS_RE = /^owners:\s*\[([^\]]*)\]/m;
+const TITLE_RE = /^title:\s*['"]?(.+?)['"]?\s*$/m;
+
+export const FRAMEWORK_BEGIN_MARKER = "<!-- BEGIN CONTEXT-TREE FRAMEWORK";
+export const FRAMEWORK_END_MARKER = "<!-- END CONTEXT-TREE FRAMEWORK -->";
+
+export interface Frontmatter {
+  title?: string;
+  owners?: string[];
+}
+
+export class Repo {
+  readonly root: string;
+
+  constructor(root?: string) {
+    this.root = resolve(root ?? process.cwd());
+  }
+
+  pathExists(relPath: string): boolean {
+    return existsSync(join(this.root, relPath));
+  }
+
+  fileContains(relPath: string, text: string): boolean {
+    const fullPath = join(this.root, relPath);
+    try {
+      const stat = statSync(fullPath);
+      if (!stat.isFile()) return false;
+      return readFileSync(fullPath, "utf-8").includes(text);
+    } catch {
+      return false;
+    }
+  }
+
+  readFile(relPath: string): string | null {
+    try {
+      return readFileSync(join(this.root, relPath), "utf-8");
+    } catch {
+      return null;
+    }
+  }
+
+  frontmatter(relPath: string): Frontmatter | null {
+    const text = this.readFile(relPath);
+    if (text === null) return null;
+    const m = text.match(FRONTMATTER_RE);
+    if (!m) return null;
+    const fm = m[1];
+    const result: Frontmatter = {};
+    const titleM = fm.match(TITLE_RE);
+    if (titleM) {
+      result.title = titleM[1].trim();
+    }
+    const ownersM = fm.match(OWNERS_RE);
+    if (ownersM) {
+      const raw = ownersM[1].trim();
+      result.owners = raw
+        ? raw.split(",").map((o) => o.trim()).filter(Boolean)
+        : [];
+    }
+    return result.title !== undefined || result.owners !== undefined
+      ? result
+      : null;
+  }
+
+  anyAgentConfig(): boolean {
+    const knownConfigs = [".claude/settings.json", ".codex/config.json"];
+    return knownConfigs.some((c) => this.pathExists(c));
+  }
+
+  isGitRepo(): boolean {
+    try {
+      return statSync(join(this.root, ".git")).isDirectory();
+    } catch {
+      return false;
+    }
+  }
+
+  hasFramework(): boolean {
+    return this.frameworkLayout() !== null;
+  }
+
+  frameworkLayout(): FrameworkLayout | null {
+    return detectFrameworkLayout(this.root);
+  }
+
+  readVersion(): string | null {
+    const versionPath = resolveFirstExistingPath(
+      this.root,
+      frameworkVersionCandidates(),
+    );
+    if (versionPath === null) return null;
+    const text = this.readFile(versionPath);
+    return text ? text.trim() : null;
+  }
+
+  progressPath(): string | null {
+    return resolveFirstExistingPath(this.root, progressFileCandidates());
+  }
+
+  preferredProgressPath(): string {
+    const layout = this.frameworkLayout();
+    if (layout === "legacy") {
+      return LEGACY_PROGRESS;
+    }
+    if (layout === "legacy-skill") {
+      return LEGACY_SKILL_PROGRESS;
+    }
+    return INSTALLED_PROGRESS;
+  }
+
+  frameworkVersionPath(): string {
+    const layout = this.frameworkLayout();
+    if (layout === "legacy") {
+      return LEGACY_VERSION;
+    }
+    if (layout === "legacy-skill") {
+      return LEGACY_SKILL_VERSION;
+    }
+    return FRAMEWORK_VERSION;
+  }
+
+  hasAgentMdMarkers(): boolean {
+    const text = this.readFile("AGENT.md");
+    if (text === null) return false;
+    return text.includes(FRAMEWORK_BEGIN_MARKER) && text.includes(FRAMEWORK_END_MARKER);
+  }
+
+  hasMembers(): boolean {
+    const membersDir = join(this.root, "members");
+    try {
+      if (!statSync(membersDir).isDirectory()) return false;
+    } catch {
+      return false;
+    }
+    return existsSync(join(membersDir, "NODE.md"));
+  }
+
+  memberCount(): number {
+    const membersDir = join(this.root, "members");
+    try {
+      if (!statSync(membersDir).isDirectory()) return 0;
+    } catch {
+      return 0;
+    }
+    let count = 0;
+    const walk = (dir: string): void => {
+      for (const entry of readdirSync(dir)) {
+        const childPath = join(dir, entry);
+        try {
+          if (!statSync(childPath).isDirectory()) continue;
+        } catch {
+          continue;
+        }
+        if (existsSync(join(childPath, "NODE.md"))) {
+          count++;
+        }
+        walk(childPath);
+      }
+    };
+    walk(membersDir);
+    return count;
+  }
+
+  hasPlaceholderNode(): boolean {
+    return this.fileContains("NODE.md", "<!-- PLACEHOLDER");
+  }
+}

package/skills/first-tree/engine/rules/agent-instructions.ts

@@ -0,0 +1,37 @@
+import { FRAMEWORK_END_MARKER } from "#skill/engine/repo.js";
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { FRAMEWORK_TEMPLATES_DIR } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (!repo.pathExists("AGENT.md")) {
+    tasks.push(
+      `AGENT.md is missing — create from \`${FRAMEWORK_TEMPLATES_DIR}/agent.md.template\``,
+    );
+  } else if (!repo.hasAgentMdMarkers()) {
+    tasks.push(
+      "AGENT.md exists but is missing framework markers — add `<!-- BEGIN CONTEXT-TREE FRAMEWORK -->` and `<!-- END CONTEXT-TREE FRAMEWORK -->` sections",
+    );
+  } else {
+    const text = repo.readFile("AGENT.md") ?? "";
+    const afterMarker = text.split(FRAMEWORK_END_MARKER);
+    if (afterMarker.length > 1) {
+      const userSection = afterMarker[1].trim();
+      const lines = userSection
+        .split("\n")
+        .filter(
+          (l) =>
+            l.trim() &&
+            !l.trim().startsWith("#") &&
+            !l.trim().startsWith("<!--"),
+        );
+      if (lines.length === 0) {
+        tasks.push(
+          "Add your project-specific instructions below the framework markers in AGENT.md",
+        );
+      }
+    }
+  }
+  return { group: "Agent Instructions", order: 3, tasks };
+}

package/skills/first-tree/engine/rules/agent-integration.ts

@@ -0,0 +1,19 @@
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { FRAMEWORK_EXAMPLES_DIR } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  if (repo.pathExists(".claude/settings.json")) {
+    if (!repo.fileContains(".claude/settings.json", "inject-tree-context")) {
+      tasks.push(
+        `Add SessionStart hook to \`.claude/settings.json\` (see \`${FRAMEWORK_EXAMPLES_DIR}/claude-code/\`)`,
+      );
+    }
+  } else if (!repo.anyAgentConfig()) {
+    tasks.push(
+      `No agent configuration detected. Configure your agent to load tree context at session start. See \`${FRAMEWORK_EXAMPLES_DIR}/\` for supported agents. You can skip this and set it up later.`,
+    );
+  }
+  return { group: "Agent Integration", order: 5, tasks };
+}

package/skills/first-tree/engine/rules/ci-validation.ts

@@ -0,0 +1,72 @@
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { INTERACTIVE_TOOL } from "#skill/engine/init.js";
+import type { Repo } from "#skill/engine/repo.js";
+import type { RuleResult } from "#skill/engine/rules/index.js";
+import { FRAMEWORK_WORKFLOWS_DIR } from "#skill/engine/runtime/asset-loader.js";
+
+export function evaluate(repo: Repo): RuleResult {
+  const tasks: string[] = [];
+  let hasValidation = false;
+  let hasPrReview = false;
+  let hasCodeowners = false;
+  const workflowsDir = join(repo.root, ".github", "workflows");
+  try {
+    if (statSync(workflowsDir).isDirectory()) {
+      for (const name of readdirSync(workflowsDir)) {
+        if (!name.endsWith(".yml") && !name.endsWith(".yaml")) continue;
+        const fullPath = join(workflowsDir, name);
+        try {
+          if (!statSync(fullPath).isFile()) continue;
+          const content = readFileSync(fullPath, "utf-8");
+          if (
+            content.includes("validate_nodes") ||
+            content.includes("validate_members")
+          ) {
+            hasValidation = true;
+          }
+          if (content.includes("run-review")) {
+            hasPrReview = true;
+          }
+          if (content.includes("generate-codeowners")) {
+            hasCodeowners = true;
+          }
+        } catch {
+          continue;
+        }
+      }
+    }
+  } catch {
+    // workflows dir doesn't exist
+  }
+  if (!hasValidation) {
+    tasks.push(
+      `No validation workflow found — copy \`${FRAMEWORK_WORKFLOWS_DIR}/validate.yml\` to \`.github/workflows/validate.yml\``,
+    );
+  }
+  if (!hasPrReview) {
+    tasks.push(
+      `Use ${INTERACTIVE_TOOL} to ask whether the user wants AI-powered PR reviews. Options:\n` +
+      "  1. **OpenRouter** — use an OpenRouter API key\n" +
+      "  2. **Claude API** — use a Claude API key directly\n" +
+      "  3. **Skip** — do not set up PR reviews\n" +
+      `If (1): copy \`${FRAMEWORK_WORKFLOWS_DIR}/pr-review.yml\` to \`.github/workflows/pr-review.yml\` as-is; the repo secret name is \`OPENROUTER_API_KEY\`. ` +
+      "If (2): copy the workflow and replace the `env` block with `ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}`, remove the `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN`, and `ANTHROPIC_DEFAULT_SONNET_MODEL` lines; the repo secret name is `ANTHROPIC_API_KEY`. " +
+      "If (3): skip this and the next task.",
+    );
+    tasks.push(
+      `Use ${INTERACTIVE_TOOL} to ask how the user wants to configure the API secret. Options:\n` +
+      "  1. **Set it now** — provide the key and the agent will run `gh secret set <SECRET_NAME> --body <KEY>`\n" +
+      "  2. **I'll do it myself** — the agent will show manual instructions\n" +
+      "If (1): ask the user to provide the key, then run `gh secret set` with the secret name from the previous step. " +
+      "If (2): tell the user to go to their repo → Settings → Secrets and variables → Actions → New repository secret, and create the secret with the name from the previous step. " +
+      "Skip this task if the user chose Skip in the previous step.",
+    );
+  }
+  if (!hasCodeowners) {
+    tasks.push(
+      `No CODEOWNERS workflow found — copy \`${FRAMEWORK_WORKFLOWS_DIR}/codeowners.yml\` to \`.github/workflows/codeowners.yml\` to auto-generate CODEOWNERS from tree ownership on every PR.`,
+    );
+  }
+  return { group: "CI / Validation", order: 6, tasks };
+}