@codedrifters/configulator 0.0.205 → 0.0.207

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/lib/index.mjs CHANGED
@@ -2645,506 +2645,522 @@ var orchestratorBundle = {
2645
2645
  }
2646
2646
  };
2647
2647
 
2648
- // src/pnpm/pnpm-workspace.ts
2649
- import { relative } from "path";
2650
- import { Component, YamlFile } from "projen";
2651
- var MINIMUM_RELEASE_AGE = {
2652
- ZERO_DAYS: 0,
2653
- ONE_HOUR: 60,
2654
- SIX_HOURS: 360,
2655
- TWELVE_HOURS: 720,
2656
- ONE_DAY: 1440,
2657
- TWO_DAYS: 2880,
2658
- THREE_DAYS: 4320,
2659
- FOUR_DAYS: 5760,
2660
- FIVE_DAYS: 7200,
2661
- SIX_DAYS: 8640,
2662
- ONE_WEEK: 10080
2663
- };
2664
- var PnpmWorkspace = class _PnpmWorkspace extends Component {
2665
- /**
2666
- * Get the pnpm workspace component of a project. If it does not exist,
2667
- * return undefined.
2668
- *
2669
- * @param project
2670
- * @returns
2671
- */
2672
- static of(project) {
2673
- const isDefined = (c) => c instanceof _PnpmWorkspace;
2674
- return project.root.components.find(isDefined);
2675
- }
2676
- constructor(project, options = {}) {
2677
- super(project);
2678
- project.tryFindObjectFile("package.json")?.addDeletionOverride("pnpm");
2679
- this.fileName = options.fileName ?? "pnpm-workspace.yaml";
2680
- this.minimumReleaseAge = options.minimumReleaseAge ?? MINIMUM_RELEASE_AGE.ONE_DAY;
2681
- this.minimumReleaseAgeExclude = options.minimumReleaseAgeExclude ? ["@codedrifters/*", ...options.minimumReleaseAgeExclude] : ["@codedrifters/*"];
2682
- this.onlyBuiltDependencies = options.onlyBuiltDependencies ? options.onlyBuiltDependencies : [];
2683
- this.ignoredBuiltDependencies = options.ignoredBuiltDependencies ? options.ignoredBuiltDependencies : [];
2684
- this.subprojects = options.subprojects ?? [];
2685
- this.defaultCatalog = options.defaultCatalog;
2686
- this.namedCatalogs = options.namedCatalogs;
2687
- project.addPackageIgnore(this.fileName);
2688
- new YamlFile(this.project, this.fileName, {
2689
- obj: () => {
2690
- const pnpmConfig = {};
2691
- const packages = new Array();
2692
- for (const subproject of project.subprojects) {
2693
- packages.push(relative(this.project.outdir, subproject.outdir));
2694
- }
2695
- const packageSet = new Set(packages);
2696
- for (const subprojectPath of this.subprojects) {
2697
- packageSet.add(subprojectPath);
2698
- }
2699
- if (this.subprojects.length > 0) {
2700
- packages.length = 0;
2701
- packages.push(...packageSet);
2702
- }
2703
- pnpmConfig.minimumReleaseAge = this.minimumReleaseAge;
2704
- if (this.minimumReleaseAgeExclude.length > 0) {
2705
- pnpmConfig.minimumReleaseAgeExclude = this.minimumReleaseAgeExclude;
2706
- }
2707
- if (this.onlyBuiltDependencies.length > 0) {
2708
- pnpmConfig.onlyBuiltDependencies = this.onlyBuiltDependencies;
2709
- }
2710
- if (this.ignoredBuiltDependencies.length > 0) {
2711
- pnpmConfig.ignoreBuiltDependencies = this.ignoredBuiltDependencies;
2712
- }
2713
- if (this.defaultCatalog && Object.keys(this.defaultCatalog).length > 0) {
2714
- pnpmConfig.catalog = this.defaultCatalog;
2715
- }
2716
- if (this.namedCatalogs && Object.keys(this.namedCatalogs).length > 0) {
2717
- pnpmConfig.namedCatalogs = this.namedCatalogs;
2718
- }
2719
- return {
2720
- ...packages.length > 0 ? { packages } : {},
2721
- ...pnpmConfig ? { ...pnpmConfig } : {}
2722
- };
2723
- }
2724
- });
2725
- }
2726
- };
2727
- var MIMIMUM_RELEASE_AGE = MINIMUM_RELEASE_AGE;
2728
-
2729
- // src/agent/bundles/pnpm.ts
2730
- var pnpmBundle = {
2731
- name: "pnpm",
2732
- description: "PNPM workspace rules and dependency management conventions",
2733
- appliesWhen: (project) => hasComponent(project, PnpmWorkspace),
2734
- rules: [
2735
- {
2736
- name: "pnpm-workspace",
2737
- description: "PNPM workspace and dependency management conventions",
2738
- scope: AGENT_RULE_SCOPE.FILE_PATTERN,
2739
- filePatterns: ["package.json", "pnpm-workspace.yaml", "pnpm-lock.yaml"],
2740
- content: [
2741
- "# PNPM Workspace Conventions",
2742
- "",
2743
- "## Package Management",
2744
- "",
2745
- "- Use **PNPM** for package management",
2746
- "- Workspace configuration in `pnpm-workspace.yaml`",
2747
- "- Dependencies managed through Projen, not directly in `package.json`",
2748
- "- **Always use workspace dependencies** (`workspace:*` or `workspace:^`) for packages within this monorepo",
2749
- "- Never use published NPM versions of internal packages; always reference the local workspace version",
2750
- "",
2751
- "## Dependency Management",
2752
- "",
2753
- "**DO:**",
2754
- "- Configure dependencies in Projen configuration files (`.projenrc.ts` or `projenrc/*.ts`)",
2755
- "- Add dependencies to `deps`, `devDeps`, or `peerDeps` arrays in project configuration",
2756
- '- Use catalog dependencies when available (e.g., `"aws-cdk-lib@catalog:"`)',
2757
- "- Ask the user to run `npx projen` and `pnpm install` after updating dependency configuration",
2758
- "",
2759
- "**DO NOT:**",
2760
- "- Run `npm install some-package`",
2761
- "- Run `pnpm add some-package`",
2762
- "- Run `yarn add some-package`",
2763
- "- Manually edit `package.json` dependencies",
2764
- "",
2765
- "Manual package installation creates conflicts with Projen-managed files."
2766
- ].join("\n"),
2767
- tags: ["workflow"]
2768
- }
2769
- ]
2770
- };
2771
-
2772
- // src/agent/bundles/pr-review.ts
2773
- var prReviewerSubAgent = {
2774
- name: "pr-reviewer",
2775
- description: "Reviews a pull request against its linked issue's acceptance criteria, then enables squash auto-merge or comments with findings",
2648
+ // src/agent/bundles/people-profile.ts
2649
+ var peopleProfileAnalystSubAgent = {
2650
+ name: "people-profile-analyst",
2651
+ description: "Researches an individual person (colleague, customer contact, vendor contact, partner contact, industry expert, or connector) from public sources and produces a structured markdown profile cross-linked to companies, software, and meeting notes. One person per session, tracked by people:* GitHub issue labels.",
2776
2652
  model: AGENT_MODEL.POWERFUL,
2777
- maxTurns: 40,
2653
+ maxTurns: 80,
2778
2654
  platforms: { cursor: { exclude: true } },
2779
2655
  prompt: [
2780
- "# PR Reviewer Agent",
2656
+ "# People Profile Analyst Agent",
2781
2657
  "",
2782
- "You review a single pull request in **{{repository.owner}}/{{repository.name}}**",
2783
- "against its linked issue's acceptance criteria, verify code quality and",
2784
- "convention compliance, and then either enable squash auto-merge or leave",
2785
- "a review comment with findings. You handle exactly **one PR per session**",
2786
- "unless invoked from the multi-PR loop skill (`/review-prs`), in which case",
2787
- "you process each eligible PR in turn.",
2658
+ "You research a single person from public sources and write a",
2659
+ "structured markdown profile. Each profile cycle runs across a small",
2660
+ "sequence of GitHub issues \u2014 one per phase \u2014 and produces a single",
2661
+ "profile file on disk plus cross-references to related entities",
2662
+ "(companies, software, meeting notes) already tracked elsewhere in",
2663
+ "the project.",
2664
+ "",
2665
+ "This agent is **domain-neutral**. It makes no assumptions about what",
2666
+ "the consuming project sells, which industry it serves, or which",
2667
+ "people matter to it. All domain-specific vocabulary, output",
2668
+ "locations, cross-reference targets, and profile-template overrides",
2669
+ "come from the invoking issue body or the consuming project's",
2670
+ "configuration.",
2671
+ "",
2672
+ "Follow your project's shared agent conventions (`AGENTS.md`,",
2673
+ "`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
2788
2674
  "",
2789
2675
  "---",
2790
2676
  "",
2791
2677
  ...PROJECT_CONTEXT_READER_SECTION,
2792
- "## Phase 1: Identify the PR",
2678
+ "## Design Principles",
2793
2679
  "",
2794
- "If a PR number was provided in your instructions, use that. Otherwise stop",
2795
- "and report that you need a PR number \u2014 do not pick one yourself.",
2680
+ "1. **One person per session.** Never profile two people in a single",
2681
+ " session, even if they came up together (e.g. co-founders).",
2682
+ "2. **Public sources only.** Use the person's own public writing,",
2683
+ " company bios, conference talks, public interviews, and similar",
2684
+ " public material. Do not attempt to access gated or paywalled",
2685
+ " content unless the invoking issue body explicitly authorizes it.",
2686
+ "3. **Filesystem durability.** The profile file is the deliverable. It",
2687
+ " is committed to disk before the profile issue closes. Downstream",
2688
+ " phases read from disk \u2014 never rely on session memory.",
2689
+ "4. **Generic over specific.** No hardcoded role types, taxonomies, or",
2690
+ " relationship assumptions. Use the generic person-role taxonomy",
2691
+ " below and let consuming projects override it.",
2692
+ "5. **Cite everything.** Every non-trivial factual claim in the",
2693
+ " profile must carry a source citation (URL plus access date).",
2694
+ "6. **Respect privacy.** Profile only public, professional information.",
2695
+ " Never capture home addresses, personal phone numbers, family",
2696
+ " details, health information, or other private data even when",
2697
+ " encountered in public sources.",
2698
+ "7. **Cross-reference, don't duplicate.** When the profile mentions a",
2699
+ " company, software product, or meeting already tracked by the",
2700
+ " consuming project, link to the existing artifact rather than",
2701
+ " duplicating its content. Do not create downstream research",
2702
+ " issues for these cross-references \u2014 only link.",
2796
2703
  "",
2797
- "## Phase 1.5: Pre-flight Eligibility Filter",
2704
+ "---",
2798
2705
  "",
2799
- "Before spending turns on a full review, run a cheap eligibility check:",
2706
+ "## Person Role Taxonomy",
2800
2707
  "",
2801
- "```bash",
2802
- "gh pr view <pr-number> --json number,title,body,headRefName,mergeable,mergeStateStatus,statusCheckRollup",
2803
- "```",
2708
+ "Pick exactly one role per person profile. The taxonomy is",
2709
+ "deliberately generic \u2014 consuming projects override it via",
2710
+ "`agentConfig.rules` if they need a domain-specific refinement.",
2804
2711
  "",
2805
- "The PR is **eligible** only when **all** of the following hold:",
2712
+ "| Role | Use for |",
2713
+ "|------|---------|",
2714
+ "| `colleague` | People inside your own organization worth tracking (teammates, cross-functional partners, leadership). |",
2715
+ "| `customer-contact` | Named individuals at existing or prospective customer accounts. |",
2716
+ "| `vendor-contact` | Named individuals at vendors, suppliers, or software providers you depend on. |",
2717
+ "| `partner-contact` | Named individuals at strategic, channel, or integration partners. |",
2718
+ "| `industry-expert` | Analysts, researchers, journalists, or well-known practitioners whose work shapes the market. |",
2719
+ "| `connector` | People who primarily provide introductions, referrals, or access across networks \u2014 advisors, investors acting as connectors, community hubs. |",
2806
2720
  "",
2807
- '1. `mergeable == "MERGEABLE"` (no merge conflicts).',
2808
- "2. No **failing** required checks in `statusCheckRollup` \u2014 CI must be",
2809
- " green or still pending. Any `FAILURE`, `TIMED_OUT`, `CANCELLED`, or",
2810
- " `ERROR` conclusion on a required check disqualifies the PR.",
2811
- "3. The PR body contains a linked issue via one of the closing keywords:",
2812
- " `Closes #N`, `Fixes #N`, or `Resolves #N` (case-insensitive).",
2721
+ "If the person plausibly fits two roles, prefer the one that reflects",
2722
+ "the **reason the profile was requested**, and note the secondary",
2723
+ "role in the profile body.",
2813
2724
  "",
2814
- "If **any** check fails, post a short comment explaining the reason and",
2815
- "stop. Do not proceed to full review.",
2725
+ "---",
2816
2726
  "",
2817
- "```bash",
2818
- "gh pr comment <pr-number> --body '<reason>'",
2727
+ "## State Machine Overview",
2728
+ "",
2729
+ "```",
2730
+ "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
2731
+ "\u2502 1. RESEARCH \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 2. DRAFT PROFILE \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 3. FOLLOWUP \u2502",
2732
+ "\u2502 Collect public \u2502 \u2502 Write the structured \u2502 \u2502 Cross-link the \u2502",
2733
+ "\u2502 sources into a \u2502 \u2502 markdown profile to \u2502 \u2502 profile to existing\u2502",
2734
+ "\u2502 bounded notes \u2502 \u2502 the configured path \u2502 \u2502 companies, software\u2502",
2735
+ "\u2502 file \u2502 \u2502 \u2502 \u2502 and meeting notes \u2502",
2736
+ "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
2819
2737
  "```",
2820
2738
  "",
2821
- "Typical reasons:",
2739
+ "**Issue labels encode the phase:**",
2822
2740
  "",
2823
- "- `Not reviewable: merge conflicts \u2014 please rebase onto the default branch.`",
2824
- "- `Not reviewable: required CI check <name> is failing.`",
2825
- "- `Not reviewable: PR body is missing a linked issue (Closes #N / Fixes #N / Resolves #N).`",
2741
+ "| Label | Phase | Session work |",
2742
+ "|-------|-------|-------------|",
2743
+ "| `people:research` | 1. Research | Gather public sources. Write a bounded research-notes file. Create the draft issue. |",
2744
+ "| `people:draft` | 2. Draft | Read the research notes. Write the structured profile to `<PROFILES_DIR>`. Create the followup issue if warranted. |",
2745
+ "| `people:followup` | 3. Followup | Read the profile. Update cross-references to existing companies, software, and meeting notes. No new downstream issues. |",
2826
2746
  "",
2827
- "## Phase 2: Gather Context",
2747
+ "All issues also carry `type:people-profile` and a `status:*` label.",
2828
2748
  "",
2829
- "```bash",
2830
- "gh pr view <pr-number> --json number,title,body,headRefName,baseRefName,isDraft,state,labels,reviews",
2831
- "gh pr diff <pr-number>",
2832
- "gh pr checks <pr-number>",
2833
- "```",
2749
+ "**Issue count per person cycle:** 1 research + 1 draft + 0\u20131 followup =",
2750
+ "**2\u20133 sessions**. The followup phase is skipped when the profile did",
2751
+ "not surface any cross-references worth linking.",
2834
2752
  "",
2835
- "Extract the linked issue number from the PR body using the closing keywords",
2836
- "(`Closes #N`, `Fixes #N`, or `Resolves #N`) identified in Phase 1.5.",
2753
+ "**Shortened paths:**",
2754
+ "- Research phase determines the person is out of scope (not",
2755
+ " relevant, insufficient public material) \u2192 research issue closes",
2756
+ " with a justification and no downstream issues are created \u2192 **1 session**.",
2757
+ "- Short profile with no cross-references needed \u2192 **2 sessions**.",
2837
2758
  "",
2838
- "Then fetch the linked issue:",
2759
+ "---",
2839
2760
  "",
2840
- "```bash",
2841
- "gh issue view <issue-number>",
2842
- "```",
2761
+ "## Configurable Paths",
2843
2762
  "",
2844
- "## Phase 3: Compare Diff to Acceptance Criteria",
2763
+ "The pipeline uses these placeholders. Consuming projects override the",
2764
+ "defaults by passing paths in the `/profile-person` skill invocation",
2765
+ "or by extending this rule in their own `agentConfig.rules`.",
2845
2766
  "",
2846
- "Read the issue body for an **Acceptance Criteria** (or equivalent) section.",
2847
- "Build a checklist from it. For each item:",
2767
+ "| Placeholder | Meaning | Default |",
2768
+ "|-------------|---------|---------|",
2769
+ "| `<PEOPLE_ROOT>` | Root folder for person profiles | `docs/people/` |",
2770
+ "| `<PROFILES_DIR>` | Final person profile files | `<PEOPLE_ROOT>/profiles/` |",
2771
+ "| `<NOTES_DIR>` | Research-notes files from Phase 1 | `<PEOPLE_ROOT>/notes/` |",
2772
+ "| `<PERSON_SLUG>` | Short kebab-case slug identifying the person | derived from the person's name |",
2773
+ "| `<COMPANIES_DIR>` | Where existing company profiles live (for cross-references) | `docs/companies/profiles/` |",
2774
+ "| `<SOFTWARE_DIR>` | Where existing software profiles live (for cross-references) | `docs/software/profiles/` |",
2775
+ "| `<MEETINGS_DIR>` | Where meeting notes live (for cross-references) | `docs/meetings/` |",
2776
+ "",
2777
+ "If `docs/project-context.md` specifies a different people-research",
2778
+ "tree or cross-reference target, prefer that. Otherwise fall back to",
2779
+ "the defaults above. Cross-reference directories are read-only \u2014 this",
2780
+ "agent never writes into them.",
2848
2781
  "",
2849
- "1. Locate the changes in the diff that satisfy it.",
2850
- "2. Mark it as `met`, `partial`, or `missing`.",
2851
- "3. Record the specific files / functions / tests that provide evidence.",
2782
+ "---",
2852
2783
  "",
2853
- "Also evaluate:",
2784
+ "## Refresh Cadence",
2854
2785
  "",
2855
- "- **Convention compliance** \u2014 PR title uses a conventional commit prefix,",
2856
- " body includes a closing keyword, branch name follows project conventions",
2857
- "- **Test coverage** \u2014 new or changed behavior has tests",
2858
- "- **CI status** \u2014 `gh pr checks` reports all required checks passing",
2859
- "- **Scope creep** \u2014 diff stays within the issue's stated scope",
2786
+ "Profiles go stale. A person changes jobs, publishes new work, or",
2787
+ "shifts focus. The pipeline supports a configurable refresh cadence:",
2860
2788
  "",
2861
- "## Phase 4: Decide and Act",
2789
+ "- **Default cadence:** 180 days from the profile's `date` frontmatter.",
2790
+ "- **Override:** the invoking issue body may specify a `refresh_days: N`",
2791
+ " field, or the consuming project may set a project-wide default in",
2792
+ " `docs/project-context.md`.",
2862
2793
  "",
2863
- "### If all acceptance criteria are met and CI is green",
2794
+ "When the `/profile-person` skill is invoked for a slug that already",
2795
+ "has a profile:",
2864
2796
  "",
2865
- "Enable squash auto-merge with branch deletion. This queues the merge to",
2866
- "happen once required checks pass; no separate approval review is needed.",
2797
+ "- If the profile is **younger** than the refresh cadence, the skill",
2798
+ " exits with a message pointing to the existing profile. Pass",
2799
+ " `force: true` in the issue body to refresh anyway.",
2800
+ "- If the profile is **older** than the refresh cadence, the pipeline",
2801
+ " proceeds in update-in-place mode: Phase 2 edits the existing file,",
2802
+ " preserves its slug, and bumps the `date` frontmatter.",
2867
2803
  "",
2868
- "```bash",
2869
- "gh pr merge <pr-number> --auto --squash --delete-branch \\",
2870
- " --subject '<conventional-commit-title>' \\",
2871
- " --body '<extended-description>'",
2872
- "```",
2804
+ "Refresh mode never changes the profile's role without an explicit",
2805
+ "override in the refresh request \u2014 role changes are material and",
2806
+ "warrant a human review step.",
2873
2807
  "",
2874
- "The squash-merge subject should follow conventional commit format (e.g.",
2875
- "`feat(scope): description`). The body should bullet the changes and end",
2876
- "with `Closes #<issue-number>`.",
2808
+ "---",
2877
2809
  "",
2878
- "### If any criterion is missing, partial, or CI is failing",
2810
+ "## Agent Loop",
2879
2811
  "",
2880
- "Post a plain comment (not a formal review block) with grouped findings:",
2812
+ "Run this loop exactly once per session. Never start a second issue.",
2881
2813
  "",
2882
- "```bash",
2883
- "gh pr comment <pr-number> --body '<grouped findings>'",
2884
- "```",
2814
+ "1. Claim one open `type:people-profile` issue using phase priority:",
2815
+ " `people:research` > `people:draft` > `people:followup`.",
2816
+ "2. Transition `status:ready` \u2192 `status:in-progress` and create the",
2817
+ " branch per your project's branch-naming convention.",
2818
+ "3. Execute the phase handler that matches the issue's `people:*`",
2819
+ " label.",
2820
+ "4. Commit, push, open a PR (if applicable), and close the issue per",
2821
+ " your project's PR workflow.",
2885
2822
  "",
2886
- "Group findings by severity (**Blocking** / **Suggested** / **Nitpick**).",
2887
- "For each blocking finding, cite the unmet acceptance criterion and the",
2888
- "file or function the gap lives in. Do **not** merge, and do **not** push",
2889
- "any commits to the PR's branch.",
2823
+ "---",
2890
2824
  "",
2891
- "Rationale for using a plain comment rather than `gh pr review",
2892
- "--request-changes`: it is lighter-weight, doesn't require the author to",
2893
- "dismiss a formal review, and composes cleanly with the multi-PR loop.",
2825
+ "## Phase 1: Research (`people:research`)",
2894
2826
  "",
2895
- "## Phase 5: Branch Cleanup and Issue Closure Verification",
2827
+ "**Goal:** Gather public sources into a bounded research-notes file.",
2896
2828
  "",
2897
- "Auto-merge may not be immediate. Poll the PR state up to 10 times, waiting",
2898
- "30 seconds between polls:",
2829
+ "**Budget:** Public web search only, unless the issue body authorizes",
2830
+ "additional sources. Write one notes file. Do not write the profile",
2831
+ "in this phase.",
2899
2832
  "",
2900
- "```bash",
2901
- "gh pr view <pr-number> --json state --jq '.state'",
2902
- "```",
2833
+ "### Steps",
2903
2834
  "",
2904
- "- **`MERGED`** \u2014 clean up locally **and** verify the linked issue closed:",
2905
- " ```bash",
2906
- " git checkout {{repository.defaultBranch}}",
2907
- " git pull origin {{repository.defaultBranch}}",
2908
- " git fetch --prune origin",
2909
- " git branch -d <branch-name> 2>/dev/null || git branch -D <branch-name> 2>/dev/null || true",
2910
- " ```",
2911
- " Then check the linked issue state:",
2912
- " ```bash",
2913
- " gh issue view <issue-number> --json state --jq '.state'",
2914
- " ```",
2915
- " If the issue is **not** `CLOSED`, close it explicitly (this covers",
2916
- " malformed or missing closing keywords on the merge commit):",
2917
- " ```bash",
2918
- " gh issue close <issue-number> --reason completed",
2919
- " gh issue comment <issue-number> --body 'PR #<pr-number> merged. Closing issue.'",
2920
- " ```",
2921
- "- **`CLOSED` (not merged)** \u2014 leave the branch in place; report the closure.",
2922
- "- **Still `OPEN`** \u2014 auto-merge is pending; report and stop without deleting.",
2835
+ "1. **Read the issue body.** It should include:",
2836
+ " - The person's name and primary affiliation (company) if known",
2837
+ " - The requested role from the taxonomy above",
2838
+ " - The reason the profile was requested (framing \u2014 what does the",
2839
+ " invoking project want to learn?)",
2840
+ " - Optional: `<PERSON_SLUG>` override, custom output paths,",
2841
+ " `refresh_days` override, `force: true` for out-of-cadence refresh",
2842
+ "",
2843
+ "2. **Derive `<PERSON_SLUG>`** if not supplied \u2014 a 2\u20134 word kebab-case",
2844
+ " summary of the person's name. Disambiguate against any existing",
2845
+ " slug under `<PROFILES_DIR>/` or `<NOTES_DIR>/` by appending a",
2846
+ " company or role qualifier (e.g. `jane-doe-acme`).",
2847
+ "",
2848
+ "3. **Check for an existing profile.** If `<PROFILES_DIR>/<PERSON_SLUG>.md`",
2849
+ " exists, read its `date` frontmatter and apply the refresh cadence",
2850
+ " rules above before proceeding.",
2851
+ "",
2852
+ "4. **Gather sources.** Prioritize in this order:",
2853
+ " - The person's own public writing (personal site, blog, newsletter)",
2854
+ " - Their current employer's bio / leadership page",
2855
+ " - Public conference talks, podcast appearances, and interviews",
2856
+ " - Public directories that the invoking issue body authorizes",
2857
+ " (LinkedIn, GitHub, company profiles, Crunchbase)",
2858
+ " - Public contributions (open-source repos, published papers)",
2859
+ "",
2860
+ "5. **Write a research-notes file** to",
2861
+ " `<NOTES_DIR>/<PERSON_SLUG>.notes.md`:",
2862
+ "",
2863
+ " ```markdown",
2864
+ " ---",
2865
+ ' title: "Research Notes: <person name>"',
2866
+ " slug: <PERSON_SLUG>",
2867
+ " role: <one of the taxonomy values>",
2868
+ " primary_company: <company name if known>",
2869
+ " date: YYYY-MM-DD",
2870
+ " parent_issue: <N>",
2871
+ " ---",
2872
+ "",
2873
+ " # Research Notes: <person name>",
2874
+ "",
2875
+ " ## Framing",
2876
+ " <why this person was requested and what to learn>",
2877
+ "",
2878
+ " ## Raw Findings",
2879
+ " - <finding> \u2014 source: <citation>",
2880
+ "",
2881
+ " ## Candidate Cross-References",
2882
+ " - **Companies mentioned:** <list of company names>",
2883
+ " - **Software mentioned:** <list of product names>",
2884
+ " - **Meetings mentioned:** <list of meeting identifiers>",
2885
+ "",
2886
+ " ## Open Questions",
2887
+ " <anything the notes could not answer from public sources>",
2888
+ "",
2889
+ " ## Sources",
2890
+ " - <source URL or file path> \u2014 <date accessed>",
2891
+ " ```",
2892
+ "",
2893
+ "6. **Create the `people:draft` issue** with `Depends on: #<research-issue>`.",
2894
+ " Its body references the notes file path, the requested role, and",
2895
+ " any refresh-mode flags.",
2896
+ "",
2897
+ "7. **Commit and push** the notes file. Close the research issue.",
2923
2898
  "",
2924
2899
  "---",
2925
2900
  "",
2926
- "## Output Format",
2901
+ "## Phase 2: Draft Profile (`people:draft`)",
2927
2902
  "",
2928
- "Return a structured report:",
2903
+ "**Goal:** Write the structured person profile from the research notes.",
2929
2904
  "",
2930
- "```",
2931
- "PR #<number> \u2014 <title>",
2932
- "Linked issue: #<issue-number>",
2933
- "Verdict: AUTO_MERGE_ENABLED | NEEDS_CHANGES | INELIGIBLE | BLOCKED",
2905
+ "**Budget:** No new web searches unless explicitly needed to fill a",
2906
+ "gap the notes flagged. Write one profile file.",
2934
2907
  "",
2935
- "Acceptance criteria:",
2936
- " [x] <criterion> \u2014 <evidence>",
2937
- " [~] <criterion> \u2014 partial: <gap>",
2938
- " [ ] <criterion> \u2014 missing",
2908
+ "### Steps",
2939
2909
  "",
2940
- "Findings:",
2941
- " - Blocking: <items>",
2942
- " - Suggested: <items>",
2943
- " - Nitpick: <items>",
2910
+ "1. **Read the research-notes file** referenced in the issue body.",
2944
2911
  "",
2945
- "Action taken: <enable-auto-merge | commented-on-the-pr | none>",
2946
- "Branch state: <merged | open | closed>",
2947
- "Issue state: <closed | open>",
2948
- "```",
2912
+ "2. **Check for duplicates / refresh.** If `<PROFILES_DIR>/<PERSON_SLUG>.md`",
2913
+ " already exists:",
2914
+ " - In refresh mode, open the existing file and update in place,",
2915
+ " preserving the slug and bumping the `date` frontmatter.",
2916
+ " - Otherwise, flag a naming collision and stop \u2014 never silently",
2917
+ " overwrite a non-trivial existing profile.",
2918
+ "",
2919
+ "3. **Write the profile** to `<PROFILES_DIR>/<PERSON_SLUG>.md` using",
2920
+ " the template below. All sections are required; use",
2921
+ " `_Not available in public sources._` when a section cannot be",
2922
+ " filled from the notes.",
2923
+ "",
2924
+ " ```markdown",
2925
+ " ---",
2926
+ ' title: "<person name>"',
2927
+ " slug: <PERSON_SLUG>",
2928
+ " role: <one of the taxonomy values>",
2929
+ " primary_company: <company name>",
2930
+ " date: YYYY-MM-DD",
2931
+ " refresh_days: <N, default 180>",
2932
+ " parent_issue: <N>",
2933
+ " notes: <NOTES_DIR>/<PERSON_SLUG>.notes.md",
2934
+ " ---",
2935
+ "",
2936
+ " # <person name>",
2937
+ "",
2938
+ " ## Summary",
2939
+ " <2\u20134 sentence elevator description: who they are, what they do,",
2940
+ " why they matter to this project>",
2941
+ "",
2942
+ " ## Classification",
2943
+ " - **Primary role:** <taxonomy value>",
2944
+ " - **Secondary role (if any):** <taxonomy value or `n/a`>",
2945
+ " - **Relevance to this project:** <1\u20132 sentences tying the person",
2946
+ " back to the framing from the notes>",
2947
+ "",
2948
+ " ## Current Position",
2949
+ " - **Company:** <primary company \u2014 link to company profile if tracked>",
2950
+ " - **Title:** <current title>",
2951
+ " - **Tenure:** <since YYYY, if known>",
2952
+ " - **Focus areas:** <what they work on day-to-day>",
2953
+ "",
2954
+ " ## Background",
2955
+ " - **Prior roles:** <short reverse-chronological list>",
2956
+ " - **Education / credentials:** <if publicly disclosed>",
2957
+ " - **Notable contributions:** <open-source, publications, talks>",
2958
+ "",
2959
+ " ## Expertise Signals",
2960
+ " <topics they write or speak about \u2014 each bullet cited to a public",
2961
+ " source>",
2962
+ "",
2963
+ " ## Positioning / Point of View",
2964
+ " <how they describe their own work and views \u2014 use their own",
2965
+ " language, cited, rather than inferred>",
2966
+ "",
2967
+ " ## Cross-References",
2968
+ " - **Companies:** <links to `<COMPANIES_DIR>/*.md` for companies",
2969
+ " already tracked by this project>",
2970
+ " - **Software:** <links to `<SOFTWARE_DIR>/*.md` for software",
2971
+ " already tracked by this project>",
2972
+ " - **Meetings:** <links to `<MEETINGS_DIR>/*.md` for meeting notes",
2973
+ " this person participated in>",
2974
+ "",
2975
+ " ## Contact Preferences",
2976
+ " <public channels only \u2014 company email if listed, social handles,",
2977
+ " speaker inquiry forms. Never private contact info.>",
2978
+ "",
2979
+ " ## Risks / Open Questions",
2980
+ " <what the profile could not answer; flag anything the followup",
2981
+ " phase should cross-reference>",
2982
+ "",
2983
+ " ## Sources",
2984
+ " - <source URL> \u2014 <date accessed>",
2985
+ " ```",
2986
+ "",
2987
+ "4. **Decide whether a followup issue is warranted.** Create a",
2988
+ " `people:followup` issue (depending on this draft issue) only if",
2989
+ " the profile's Candidate Cross-References lists at least one",
2990
+ " company, software product, or meeting already tracked by the",
2991
+ " consuming project. Otherwise, note in the draft issue's closing",
2992
+ " comment that no followup is needed.",
2993
+ "",
2994
+ "5. **Commit and push** the profile file. Close the draft issue.",
2949
2995
  "",
2950
2996
  "---",
2951
2997
  "",
2952
- "## Rules",
2998
+ "## Phase 3: Followup (`people:followup`)",
2953
2999
  "",
2954
- "1. **One PR per session** when invoked directly (`/review-pr`). When",
2955
- " invoked from the multi-PR loop (`/review-prs`), process every eligible",
2956
- " PR in turn.",
2957
- "2. **Never merge without a linked issue.** If the PR body has no",
2958
- " `Closes #N` / `Fixes #N` / `Resolves #N`, comment and stop.",
2959
- "3. **Never merge with failing CI.** Even if every criterion is met,",
2960
- " block on red checks.",
2961
- "4. **Never bypass review conventions.** Always use `--squash`, `--auto`,",
2962
- " and `--delete-branch` for merges. Do not force-merge.",
2963
- "5. **Do not implement code.** You review, decide, and orchestrate. If",
2964
- " the PR needs changes, comment and stop.",
2965
- "6. **Never push commits to the PR's branch.** If the PR needs changes,",
2966
- " comment and stop \u2014 do not attempt to fix it yourself. The PR author",
2967
- " owns the branch; pushing to someone else's branch is out of scope.",
2968
- "7. **In loop mode (`/review-prs`), never stop early.** If any review",
2969
- " fails, comment and move to the next PR. Only abort the loop on a",
2970
- " fatal error (e.g. `gh` auth failure, network outage).",
2971
- "8. **Follow CLAUDE.md conventions** for all `git` and `gh` operations."
2972
- ].join("\n")
2973
- };
2974
- var reviewPrSkill = {
2975
- name: "review-pr",
2976
- description: "Review a single pull request against its linked issue's acceptance criteria, then enable squash auto-merge or comment with findings",
2977
- disableModelInvocation: true,
2978
- userInvocable: true,
2979
- context: "fork",
2980
- agent: "pr-reviewer",
2981
- platforms: { cursor: { exclude: true } },
2982
- instructions: [
2983
- "# Review Pull Request",
3000
+ "**Goal:** Populate the profile's `## Cross-References` section with",
3001
+ "links to existing artifacts \u2014 companies, software, meetings \u2014 that",
3002
+ "the consuming project already tracks.",
2984
3003
  "",
2985
- "Run a full PR review against the linked issue's acceptance criteria,",
2986
- "then either enable squash auto-merge or post a findings comment.",
3004
+ "**Budget:** No new web searches. No new downstream research issues.",
3005
+ "Read the candidate cross-references, resolve them against the",
3006
+ "configured directories, update the profile.",
2987
3007
  "",
2988
- "## Usage",
3008
+ "### Steps",
2989
3009
  "",
2990
- "/review-pr <pr-number>",
3010
+ "1. **Read the profile file** referenced in the issue body.",
2991
3011
  "",
2992
- "## What This Skill Does",
3012
+ "2. **Resolve company cross-references.** For each company named in",
3013
+ " the profile's research notes or body text, look for a matching",
3014
+ " file under `<COMPANIES_DIR>/`. If found, link it under",
3015
+ " `## Cross-References > Companies`. If not found, leave a TODO",
3016
+ " comment naming the company \u2014 the invoking project's team decides",
3017
+ " whether to kick off a separate company-profile pipeline.",
2993
3018
  "",
2994
- "1. Runs a pre-flight eligibility filter (mergeable, CI not failing, has linked issue)",
2995
- "2. Fetches the PR, its diff, CI status, and the linked issue",
2996
- "3. Builds a checklist from the issue's acceptance criteria",
2997
- "4. Compares the diff against each criterion",
2998
- "5. Verifies PR conventions (title, closing keyword, branch name)",
2999
- "6. Verifies CI is green",
3000
- "7. **If all checks pass:** enables squash auto-merge (with `--delete-branch`)",
3001
- "8. **If any check fails:** posts a findings comment via `gh pr comment`",
3002
- "9. After merge, verifies the linked issue is closed and closes it if not",
3003
- "10. Cleans up the local branch after merge",
3019
+ "3. **Resolve software cross-references.** Same pattern against",
3020
+ " `<SOFTWARE_DIR>/`. Link what matches; leave TODOs for what",
3021
+ " doesn't.",
3004
3022
  "",
3005
- "## Input",
3023
+ "4. **Resolve meeting cross-references.** For meetings the person",
3024
+ " participated in, look for a matching file under `<MEETINGS_DIR>/`",
3025
+ " by date or slug. Link matches; leave TODOs otherwise.",
3006
3026
  "",
3007
- "Provide the PR number to review. The skill resolves the linked issue from",
3008
- "the PR body (`Closes #N` / `Fixes #N` / `Resolves #N`).",
3027
+ "5. **Do not open downstream issues.** This pipeline emits no",
3028
+ " `company:research`, `research:scope`, or similar issues. Cross-",
3029
+ " references are link-only; downstream research is a separate",
3030
+ " human decision.",
3009
3031
  "",
3010
- "## Output",
3032
+ "6. **Commit and push** the updated profile. Close the followup issue.",
3011
3033
  "",
3012
- "A structured report covering verdict, per-criterion status, findings",
3013
- "grouped by severity, the action taken, and the final branch / issue state.",
3034
+ "---",
3014
3035
  "",
3015
- "## Composability",
3036
+ "## Output Boundaries",
3016
3037
  "",
3017
- "This skill is generic and can be composed with the `github-workflow`",
3018
- "bundle. The reviewer never implements code and never pushes to the PR",
3019
- "branch \u2014 it only reviews, decides, and orchestrates merge or comment."
3038
+ "This agent writes **only** to:",
3039
+ "",
3040
+ "- `<NOTES_DIR>/` \u2014 research-notes files (Phase 1)",
3041
+ "- `<PROFILES_DIR>/` \u2014 person profiles (Phase 2, updated in Phase 3)",
3042
+ "",
3043
+ "The pipeline produces **profiles and notes only**. It does not",
3044
+ "create new companies, software evaluations, meeting notes, or any",
3045
+ "other downstream artifacts \u2014 it only links to those that already",
3046
+ "exist under the configured cross-reference directories. Keep this",
3047
+ "boundary clean so the people-profile pipeline stays generic and",
3048
+ "cheap to run.",
3049
+ "",
3050
+ "---",
3051
+ "",
3052
+ "## Rules",
3053
+ "",
3054
+ "- **One person per session.** Never profile two people back-to-back.",
3055
+ "- **Persist before closing.** Every phase must write its output file",
3056
+ " before closing its issue.",
3057
+ "- **Cite everything.** Profile claims without source citations do not",
3058
+ " belong in the deliverable.",
3059
+ "- **Respect privacy.** Never record private contact details, family",
3060
+ " information, or other non-professional personal data, even when",
3061
+ " encountered in a public source.",
3062
+ "- **Cross-reference, don't duplicate.** Link to existing company,",
3063
+ " software, and meeting artifacts rather than re-describing them.",
3064
+ "- **No downstream issue creation.** Phase 3 emits no new research,",
3065
+ " profile, or requirement issues. Only link.",
3066
+ "- **Refresh, don't fork.** When a profile exists and is past its",
3067
+ " cadence, update in place rather than creating a new slug."
3020
3068
  ].join("\n")
3021
3069
  };
3022
- var reviewPrsSkill = {
3023
- name: "review-prs",
3024
- description: "Loop over every eligible open pull request in the repository and review each one through the full pipeline",
3070
+ var profilePersonSkill = {
3071
+ name: "profile-person",
3072
+ description: "Kick off a people-profile pipeline. Creates a people:research issue for the given person and dispatches Phase 1 (Research) in the people-profile-analyst agent.",
3025
3073
  disableModelInvocation: true,
3026
3074
  userInvocable: true,
3027
3075
  context: "fork",
3028
- agent: "pr-reviewer",
3076
+ agent: "people-profile-analyst",
3029
3077
  platforms: { cursor: { exclude: true } },
3030
3078
  instructions: [
3031
- "# Review All Eligible Pull Requests",
3079
+ "# Profile Person",
3032
3080
  "",
3033
- "Run the pr-reviewer pipeline over every eligible open PR in",
3034
- "**{{repository.owner}}/{{repository.name}}**, one after another, until",
3035
- "the eligible queue is empty.",
3081
+ "Kick off a people-profile pipeline. Creates a `people:research`",
3082
+ "issue carrying the person's name, role, primary affiliation, and",
3083
+ "framing, then dispatches Phase 1 (Research) in the",
3084
+ "people-profile-analyst agent.",
3036
3085
  "",
3037
3086
  "## Usage",
3038
3087
  "",
3039
- "/review-prs",
3040
- "",
3041
- "## What This Skill Does",
3042
- "",
3043
- "### Step 1: Enumerate open PRs",
3044
- "",
3045
- "```bash",
3046
- "gh pr list --json number,title,body,headRefName,mergeable,mergeStateStatus,statusCheckRollup --limit 50",
3047
- "```",
3048
- "",
3049
- "### Step 2: Filter to eligible PRs",
3050
- "",
3051
- "A PR is **eligible** when all of the following hold:",
3088
+ "/profile-person <person-name>",
3052
3089
  "",
3053
- '1. `state == "OPEN"` (implicit from `gh pr list`).',
3054
- '2. `mergeable == "MERGEABLE"` (no conflicts).',
3055
- "3. No required check in `statusCheckRollup` has a failing conclusion",
3056
- " (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ERROR`). CI green or still",
3057
- " pending is fine.",
3058
- "4. The PR body contains a linked issue (`Closes #N` / `Fixes #N` /",
3059
- " `Resolves #N`, case-insensitive).",
3090
+ "Optional extensions in the issue body:",
3091
+ "- `role: <colleague | customer-contact | vendor-contact |",
3092
+ " partner-contact | industry-expert | connector>` \u2014 override the",
3093
+ " default role inference",
3094
+ "- `company: <name>` \u2014 primary company affiliation if not obvious",
3095
+ " from the name",
3096
+ "- `framing: <text>` \u2014 why this profile was requested and what to learn",
3097
+ "- `slug: <kebab-case>` \u2014 override the derived person slug",
3098
+ "- `refresh_days: <N>` \u2014 override the default 180-day refresh cadence",
3099
+ "- `force: true` \u2014 refresh even if the profile is younger than the",
3100
+ " cadence window",
3101
+ "- `sources: <list>` \u2014 additional authorized sources beyond public web",
3060
3102
  "",
3061
- "Drop any PR that fails the filter from the queue. Do not comment on",
3062
- "them from this skill \u2014 the individual `/review-pr` invocation handles",
3063
- "the inline rejection comment when run on a specific PR.",
3103
+ "## Default Paths",
3064
3104
  "",
3065
- "### Step 3: Process each eligible PR",
3105
+ "If the project has no override in `docs/project-context.md` or",
3106
+ "`agentConfig.rules`, outputs land under:",
3066
3107
  "",
3067
- "For every eligible PR, invoke the full pr-reviewer pipeline",
3068
- "(Phases 1 through 5) as if `/review-pr <number>` had been called",
3069
- "directly:",
3108
+ "- `docs/people/notes/<slug>.notes.md`",
3109
+ "- `docs/people/profiles/<slug>.md`",
3070
3110
  "",
3071
- "- Gather context (diff, checks, linked issue)",
3072
- "- Compare diff to acceptance criteria",
3073
- "- Decide and act (enable auto-merge **or** post findings comment)",
3074
- "- Verify branch / issue cleanup after merge",
3111
+ "Cross-references are resolved against:",
3075
3112
  "",
3076
- "Continue to the next PR after each one completes. Never stop the loop",
3077
- "early because a single PR's review failed \u2014 comment and move on.",
3113
+ "- `docs/companies/profiles/`",
3114
+ "- `docs/software/profiles/`",
3115
+ "- `docs/meetings/`",
3078
3116
  "",
3079
- "### Step 4: Stop when the queue is empty",
3117
+ "## Steps",
3080
3118
  "",
3081
- "When no eligible PRs remain, emit a final summary listing every PR",
3082
- "processed and the verdict for each, then stop.",
3119
+ "1. Create a `people:research` issue with `type:people-profile`,",
3120
+ " `priority:medium`, and `status:ready`. Body must include the",
3121
+ " person's name, selected role, primary company, framing, and any",
3122
+ " overrides.",
3123
+ "2. Execute Phase 1 (Research) of the people-profile-analyst agent.",
3124
+ "3. Phase 1 creates the `people:draft` issue. Phase 2 may create a",
3125
+ " `people:followup` issue. Each downstream issue declares its",
3126
+ " `Depends on:` predecessor.",
3083
3127
  "",
3084
3128
  "## Output",
3085
3129
  "",
3086
- "Per-PR structured report (same shape as `/review-pr`), followed by a",
3087
- "one-line-per-PR summary at the end:",
3088
- "",
3089
- "```",
3090
- "Summary:",
3091
- " PR #<n>: <verdict>",
3092
- " PR #<n>: <verdict>",
3093
- " ...",
3094
- "Total processed: <count>",
3095
- "```",
3096
- "",
3097
- "## Failure Handling",
3098
- "",
3099
- "Only abort the loop on a fatal error (e.g. `gh` authentication failure,",
3100
- "network outage). A failed review for an individual PR is not fatal \u2014",
3101
- "comment on that PR and continue with the next."
3130
+ "- A research-notes file under the project's notes directory",
3131
+ "- A single person profile under the profiles directory",
3132
+ "- Cross-references to existing companies, software, and meetings",
3133
+ " tracked elsewhere in the project",
3134
+ "- This pipeline produces **profiles only** \u2014 it does not create",
3135
+ " companies, software, meetings, or any other downstream artifacts."
3102
3136
  ].join("\n")
3103
3137
  };
3104
- var prReviewBundle = {
3105
- name: "pr-review",
3106
- description: "Pull request review workflow: verifies PRs against their linked issues' acceptance criteria and orchestrates squash-merge, single or looped over all eligible PRs",
3107
- // Default-apply: the PR review workflow is safe to include everywhere,
3108
- // and keeping review/merge policy centralised in the pr-reviewer agent
3109
- // means consumers get consistent behaviour out of the box. Consumers can
3110
- // still exclude it explicitly via `excludeBundles` if desired.
3111
- appliesWhen: () => true,
3138
+ var peopleProfileBundle = {
3139
+ name: "people-profile",
3140
+ description: "People research and profiling pipeline: research, draft profile, followup. Opt-in only; domain-neutral; filesystem-durable between phases; cross-references existing companies, software, and meeting notes without creating new downstream issues.",
3141
+ appliesWhen: () => false,
3112
3142
  rules: [
3113
3143
  {
3114
- name: "pr-review-workflow",
3115
- description: "Describes the /review-pr and /review-prs skills and their delegation to the pr-reviewer sub-agent",
3144
+ name: "people-profile-workflow",
3145
+ description: "Describes the 3-phase people-profile pipeline, the people:* label taxonomy, the cross-reference model, and the boundary against downstream research agents.",
3116
3146
  scope: AGENT_RULE_SCOPE.ALWAYS,
3117
3147
  content: [
3118
- "# PR Review Workflow",
3119
- "",
3120
- "Two skills are available, both backed by the same `pr-reviewer`",
3121
- "sub-agent:",
3122
- "",
3123
- "- **`/review-pr <pr-number>`** \u2014 review a single targeted PR.",
3124
- "- **`/review-prs`** \u2014 loop over every eligible open PR in the",
3125
- " repository and review each one in turn.",
3148
+ "# People Profile Workflow",
3126
3149
  "",
3127
- "The `pr-reviewer` sub-agent:",
3150
+ "Use `/profile-person <person-name>` to kick off a person",
3151
+ "research and profiling pipeline. The pipeline runs in up to 3",
3152
+ "phases \u2014 research, draft, followup \u2014 each tracked by its own",
3153
+ "GitHub issue labeled `people:research`, `people:draft`, or",
3154
+ "`people:followup`. All issues carry `type:people-profile`.",
3128
3155
  "",
3129
- "1. Runs a pre-flight eligibility filter (mergeable, CI not failing,",
3130
- " has a linked issue). Ineligible PRs get a short comment and are",
3131
- " skipped.",
3132
- "2. Fetches the PR, its diff, CI status, and the linked issue",
3133
- "3. Builds a checklist from the issue's acceptance criteria",
3134
- "4. Verifies the diff satisfies each criterion and that CI is green",
3135
- "5. **Enables squash auto-merge** (with `--delete-branch`) when all",
3136
- " checks pass \u2014 no explicit approval review",
3137
- "6. **Comments with grouped findings** when any check fails (plain",
3138
- " `gh pr comment`, not a formal `--request-changes` review)",
3139
- "7. After a successful merge, verifies the linked issue is closed",
3140
- " and closes it explicitly if the merge commit did not",
3141
- "8. Cleans up the local branch after merge",
3156
+ "The pipeline produces **person profiles only**. Cross-references",
3157
+ "to companies, software products, and meeting notes are link-only",
3158
+ "\u2014 the followup phase never creates new downstream research,",
3159
+ "profile, or requirement issues.",
3142
3160
  "",
3143
- "The reviewer **never** implements code and **never** pushes commits",
3144
- "to a PR's branch \u2014 it only reviews, decides, and orchestrates merge",
3145
- "or comment. In loop mode, a failed review for one PR never stops",
3146
- "the loop; the reviewer comments and moves on. See the `pr-reviewer`",
3147
- "agent definition for the full phase-by-phase contract."
3161
+ "See the `people-profile-analyst` agent definition for full",
3162
+ "workflow details, default paths, the person-role taxonomy, the",
3163
+ "refresh cadence rules, and phase-by-phase instructions."
3148
3164
  ].join("\n"),
3149
3165
  platforms: {
3150
3166
  cursor: { exclude: true }
@@ -3152,368 +3168,1384 @@ var prReviewBundle = {
3152
3168
  tags: ["workflow"]
3153
3169
  }
3154
3170
  ],
3155
- skills: [reviewPrSkill, reviewPrsSkill],
3156
- subAgents: [prReviewerSubAgent]
3171
+ skills: [profilePersonSkill],
3172
+ subAgents: [peopleProfileAnalystSubAgent],
3173
+ labels: [
3174
+ {
3175
+ name: "type:people-profile",
3176
+ color: "0E8A16",
3177
+ description: "Work that produces or maintains a person profile or its research notes"
3178
+ },
3179
+ {
3180
+ name: "people:research",
3181
+ color: "C5DEF5",
3182
+ description: "Phase 1: gather public sources about a person into a research-notes file"
3183
+ },
3184
+ {
3185
+ name: "people:draft",
3186
+ color: "BFDADC",
3187
+ description: "Phase 2: write the structured person profile from research notes"
3188
+ },
3189
+ {
3190
+ name: "people:followup",
3191
+ color: "D4C5F9",
3192
+ description: "Phase 3: cross-link the profile to existing companies, software, and meeting notes"
3193
+ }
3194
+ ]
3157
3195
  };
3158
3196
 
3159
- // src/agent/bundles/projen.ts
3160
- var projenBundle = {
3161
- name: "projen",
3162
- description: "Projen conventions, synthesis workflow, .projenrc.ts patterns",
3163
- appliesWhen: (project) => hasDep(project, "projen"),
3197
+ // src/pnpm/pnpm-workspace.ts
3198
+ import { relative } from "path";
3199
+ import { Component, YamlFile } from "projen";
3200
+ var MINIMUM_RELEASE_AGE = {
3201
+ ZERO_DAYS: 0,
3202
+ ONE_HOUR: 60,
3203
+ SIX_HOURS: 360,
3204
+ TWELVE_HOURS: 720,
3205
+ ONE_DAY: 1440,
3206
+ TWO_DAYS: 2880,
3207
+ THREE_DAYS: 4320,
3208
+ FOUR_DAYS: 5760,
3209
+ FIVE_DAYS: 7200,
3210
+ SIX_DAYS: 8640,
3211
+ ONE_WEEK: 10080
3212
+ };
3213
+ var PnpmWorkspace = class _PnpmWorkspace extends Component {
3214
+ /**
3215
+ * Get the pnpm workspace component of a project. If it does not exist,
3216
+ * return undefined.
3217
+ *
3218
+ * @param project
3219
+ * @returns
3220
+ */
3221
+ static of(project) {
3222
+ const isDefined = (c) => c instanceof _PnpmWorkspace;
3223
+ return project.root.components.find(isDefined);
3224
+ }
3225
+ constructor(project, options = {}) {
3226
+ super(project);
3227
+ project.tryFindObjectFile("package.json")?.addDeletionOverride("pnpm");
3228
+ this.fileName = options.fileName ?? "pnpm-workspace.yaml";
3229
+ this.minimumReleaseAge = options.minimumReleaseAge ?? MINIMUM_RELEASE_AGE.ONE_DAY;
3230
+ this.minimumReleaseAgeExclude = options.minimumReleaseAgeExclude ? ["@codedrifters/*", ...options.minimumReleaseAgeExclude] : ["@codedrifters/*"];
3231
+ this.onlyBuiltDependencies = options.onlyBuiltDependencies ? options.onlyBuiltDependencies : [];
3232
+ this.ignoredBuiltDependencies = options.ignoredBuiltDependencies ? options.ignoredBuiltDependencies : [];
3233
+ this.subprojects = options.subprojects ?? [];
3234
+ this.defaultCatalog = options.defaultCatalog;
3235
+ this.namedCatalogs = options.namedCatalogs;
3236
+ project.addPackageIgnore(this.fileName);
3237
+ new YamlFile(this.project, this.fileName, {
3238
+ obj: () => {
3239
+ const pnpmConfig = {};
3240
+ const packages = new Array();
3241
+ for (const subproject of project.subprojects) {
3242
+ packages.push(relative(this.project.outdir, subproject.outdir));
3243
+ }
3244
+ const packageSet = new Set(packages);
3245
+ for (const subprojectPath of this.subprojects) {
3246
+ packageSet.add(subprojectPath);
3247
+ }
3248
+ if (this.subprojects.length > 0) {
3249
+ packages.length = 0;
3250
+ packages.push(...packageSet);
3251
+ }
3252
+ pnpmConfig.minimumReleaseAge = this.minimumReleaseAge;
3253
+ if (this.minimumReleaseAgeExclude.length > 0) {
3254
+ pnpmConfig.minimumReleaseAgeExclude = this.minimumReleaseAgeExclude;
3255
+ }
3256
+ if (this.onlyBuiltDependencies.length > 0) {
3257
+ pnpmConfig.onlyBuiltDependencies = this.onlyBuiltDependencies;
3258
+ }
3259
+ if (this.ignoredBuiltDependencies.length > 0) {
3260
+ pnpmConfig.ignoreBuiltDependencies = this.ignoredBuiltDependencies;
3261
+ }
3262
+ if (this.defaultCatalog && Object.keys(this.defaultCatalog).length > 0) {
3263
+ pnpmConfig.catalog = this.defaultCatalog;
3264
+ }
3265
+ if (this.namedCatalogs && Object.keys(this.namedCatalogs).length > 0) {
3266
+ pnpmConfig.namedCatalogs = this.namedCatalogs;
3267
+ }
3268
+ return {
3269
+ ...packages.length > 0 ? { packages } : {},
3270
+ ...pnpmConfig ? { ...pnpmConfig } : {}
3271
+ };
3272
+ }
3273
+ });
3274
+ }
3275
+ };
3276
+ var MIMIMUM_RELEASE_AGE = MINIMUM_RELEASE_AGE;
3277
+
3278
+ // src/agent/bundles/pnpm.ts
3279
+ var pnpmBundle = {
3280
+ name: "pnpm",
3281
+ description: "PNPM workspace rules and dependency management conventions",
3282
+ appliesWhen: (project) => hasComponent(project, PnpmWorkspace),
3164
3283
  rules: [
3165
3284
  {
3166
- name: "development-commands",
3167
- description: "Projen development commands for building, testing, linting, and validating changes",
3168
- scope: AGENT_RULE_SCOPE.ALWAYS,
3285
+ name: "pnpm-workspace",
3286
+ description: "PNPM workspace and dependency management conventions",
3287
+ scope: AGENT_RULE_SCOPE.FILE_PATTERN,
3288
+ filePatterns: ["package.json", "pnpm-workspace.yaml", "pnpm-lock.yaml"],
3169
3289
  content: [
3170
- "# Development Commands",
3171
- "",
3172
- "This project uses Projen to manage configuration and Turborepo to orchestrate builds across the monorepo. Run all commands from the **repository root** unless otherwise noted.",
3173
- "",
3174
- "## Synthesizing Projen Configuration",
3175
- "",
3176
- "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files:",
3177
- "",
3178
- "```sh",
3179
- "npx projen",
3180
- "pnpm install",
3181
- "```",
3182
- "",
3183
- "Both steps are required \u2014 `npx projen` regenerates files, `pnpm install` updates the lockfile to match.",
3184
- "",
3185
- "## Building",
3186
- "",
3187
- "**Full monorepo build** (compile + test + package, all sub-packages via Turborepo):",
3188
- "",
3189
- "```sh",
3190
- "pnpm build:all",
3191
- "```",
3192
- "",
3193
- "**Root project only** (synthesize + compile + lint):",
3194
- "",
3195
- "```sh",
3196
- "pnpm build",
3197
- "```",
3198
- "",
3199
- "**Single sub-package** (compile only):",
3200
- "",
3201
- "```sh",
3202
- "pnpm --filter @codedrifters/<package> compile",
3203
- "```",
3204
- "",
3205
- "Replace `<package>` with `configulator`, `constructs`, or `utils`.",
3206
- "",
3207
- "## Testing",
3208
- "",
3209
- "**Run tests for a single sub-package:**",
3210
- "",
3211
- "```sh",
3212
- "pnpm --filter @codedrifters/<package> test",
3213
- "```",
3214
- "",
3215
- "This runs ESLint + Vitest for the specified package.",
3216
- "",
3217
- "**Run only Vitest (skip lint) in a sub-package:**",
3218
- "",
3219
- "```sh",
3220
- "cd packages/@codedrifters/<package>",
3221
- "pnpm exec vitest run",
3222
- "```",
3223
- "",
3224
- "**Run a specific test file:**",
3225
- "",
3226
- "```sh",
3227
- "cd packages/@codedrifters/<package>",
3228
- "pnpm exec vitest run src/path/to/file.test.ts",
3229
- "```",
3230
- "",
3231
- "## Linting",
3232
- "",
3233
- "**Lint the root project:**",
3234
- "",
3235
- "```sh",
3236
- "pnpm eslint",
3237
- "```",
3238
- "",
3239
- "**Lint a single sub-package:**",
3240
- "",
3241
- "```sh",
3242
- "pnpm --filter @codedrifters/<package> eslint",
3243
- "```",
3244
- "",
3245
- "## Resetting Build Artifacts",
3246
- "",
3247
- "**Reset everything** (all packages + root):",
3248
- "",
3249
- "```sh",
3250
- "pnpm reset:all",
3251
- "```",
3290
+ "# PNPM Workspace Conventions",
3252
3291
  "",
3253
- "**Reset root only:**",
3292
+ "## Package Management",
3254
3293
  "",
3255
- "```sh",
3256
- "pnpm reset",
3257
- "```",
3294
+ "- Use **PNPM** for package management",
3295
+ "- Workspace configuration in `pnpm-workspace.yaml`",
3296
+ "- Dependencies managed through Projen, not directly in `package.json`",
3297
+ "- **Always use workspace dependencies** (`workspace:*` or `workspace:^`) for packages within this monorepo",
3298
+ "- Never use published NPM versions of internal packages; always reference the local workspace version",
3258
3299
  "",
3259
- "## Validating Changes Are Complete",
3300
+ "## Dependency Management",
3260
3301
  "",
3261
- "After finishing implementation work, validate that changes are correct by running the appropriate commands depending on what was changed:",
3302
+ "**DO:**",
3303
+ "- Configure dependencies in Projen configuration files (`.projenrc.ts` or `projenrc/*.ts`)",
3304
+ "- Add dependencies to `deps`, `devDeps`, or `peerDeps` arrays in project configuration",
3305
+ '- Use catalog dependencies when available (e.g., `"aws-cdk-lib@catalog:"`)',
3306
+ "- Ask the user to run `npx projen` and `pnpm install` after updating dependency configuration",
3262
3307
  "",
3263
- "1. **Projen config changes** (`projenrc/`, `.projenrc.ts`):",
3264
- " - Run `npx projen` then `pnpm install`",
3265
- " - Verify no unexpected generated file changes with `git diff`",
3308
+ "**DO NOT:**",
3309
+ "- Run `npm install some-package`",
3310
+ "- Run `pnpm add some-package`",
3311
+ "- Run `yarn add some-package`",
3312
+ "- Manually edit `package.json` dependencies",
3266
3313
  "",
3267
- "2. **Source code changes** (in a sub-package):",
3268
- " - Compile: `pnpm --filter @codedrifters/<package> compile`",
3269
- " - Test: `pnpm --filter @codedrifters/<package> test`",
3270
- "",
3271
- "3. **Changes spanning multiple packages**:",
3272
- " - Run `pnpm build:all` to validate the full monorepo build",
3273
- "",
3274
- "4. **Root-level changes** (projenrc, root config):",
3275
- " - Run `pnpm build` to validate root synthesis + compilation + lint",
3276
- "",
3277
- "## Command Reference",
3278
- "",
3279
- "| Task | Command |",
3280
- "|------|---------|",
3281
- "| Synthesize projen | `npx projen` |",
3282
- "| Install deps | `pnpm install` |",
3283
- "| Full monorepo build | `pnpm build:all` |",
3284
- "| Root build only | `pnpm build` |",
3285
- "| Compile one package | `pnpm --filter @codedrifters/<pkg> compile` |",
3286
- "| Test one package | `pnpm --filter @codedrifters/<pkg> test` |",
3287
- "| Lint one package | `pnpm --filter @codedrifters/<pkg> eslint` |",
3288
- "| Lint root | `pnpm eslint` |",
3289
- "| Reset all artifacts | `pnpm reset:all` |"
3314
+ "Manual package installation creates conflicts with Projen-managed files."
3290
3315
  ].join("\n"),
3291
3316
  tags: ["workflow"]
3292
- },
3317
+ }
3318
+ ]
3319
+ };
3320
+
3321
+ // src/agent/bundles/pr-review.ts
3322
+ var prReviewerSubAgent = {
3323
+ name: "pr-reviewer",
3324
+ description: "Reviews a pull request against its linked issue's acceptance criteria, then enables squash auto-merge or comments with findings",
3325
+ model: AGENT_MODEL.POWERFUL,
3326
+ maxTurns: 40,
3327
+ platforms: { cursor: { exclude: true } },
3328
+ prompt: [
3329
+ "# PR Reviewer Agent",
3330
+ "",
3331
+ "You review a single pull request in **{{repository.owner}}/{{repository.name}}**",
3332
+ "against its linked issue's acceptance criteria, verify code quality and",
3333
+ "convention compliance, and then either enable squash auto-merge or leave",
3334
+ "a review comment with findings. You handle exactly **one PR per session**",
3335
+ "unless invoked from the multi-PR loop skill (`/review-prs`), in which case",
3336
+ "you process each eligible PR in turn.",
3337
+ "",
3338
+ "---",
3339
+ "",
3340
+ ...PROJECT_CONTEXT_READER_SECTION,
3341
+ "## Phase 1: Identify the PR",
3342
+ "",
3343
+ "If a PR number was provided in your instructions, use that. Otherwise stop",
3344
+ "and report that you need a PR number \u2014 do not pick one yourself.",
3345
+ "",
3346
+ "## Phase 1.5: Pre-flight Eligibility Filter",
3347
+ "",
3348
+ "Before spending turns on a full review, run a cheap eligibility check:",
3349
+ "",
3350
+ "```bash",
3351
+ "gh pr view <pr-number> --json number,title,body,headRefName,mergeable,mergeStateStatus,statusCheckRollup",
3352
+ "```",
3353
+ "",
3354
+ "The PR is **eligible** only when **all** of the following hold:",
3355
+ "",
3356
+ '1. `mergeable == "MERGEABLE"` (no merge conflicts).',
3357
+ "2. No **failing** required checks in `statusCheckRollup` \u2014 CI must be",
3358
+ " green or still pending. Any `FAILURE`, `TIMED_OUT`, `CANCELLED`, or",
3359
+ " `ERROR` conclusion on a required check disqualifies the PR.",
3360
+ "3. The PR body contains a linked issue via one of the closing keywords:",
3361
+ " `Closes #N`, `Fixes #N`, or `Resolves #N` (case-insensitive).",
3362
+ "",
3363
+ "If **any** check fails, post a short comment explaining the reason and",
3364
+ "stop. Do not proceed to full review.",
3365
+ "",
3366
+ "```bash",
3367
+ "gh pr comment <pr-number> --body '<reason>'",
3368
+ "```",
3369
+ "",
3370
+ "Typical reasons:",
3371
+ "",
3372
+ "- `Not reviewable: merge conflicts \u2014 please rebase onto the default branch.`",
3373
+ "- `Not reviewable: required CI check <name> is failing.`",
3374
+ "- `Not reviewable: PR body is missing a linked issue (Closes #N / Fixes #N / Resolves #N).`",
3375
+ "",
3376
+ "## Phase 2: Gather Context",
3377
+ "",
3378
+ "```bash",
3379
+ "gh pr view <pr-number> --json number,title,body,headRefName,baseRefName,isDraft,state,labels,reviews",
3380
+ "gh pr diff <pr-number>",
3381
+ "gh pr checks <pr-number>",
3382
+ "```",
3383
+ "",
3384
+ "Extract the linked issue number from the PR body using the closing keywords",
3385
+ "(`Closes #N`, `Fixes #N`, or `Resolves #N`) identified in Phase 1.5.",
3386
+ "",
3387
+ "Then fetch the linked issue:",
3388
+ "",
3389
+ "```bash",
3390
+ "gh issue view <issue-number>",
3391
+ "```",
3392
+ "",
3393
+ "## Phase 3: Compare Diff to Acceptance Criteria",
3394
+ "",
3395
+ "Read the issue body for an **Acceptance Criteria** (or equivalent) section.",
3396
+ "Build a checklist from it. For each item:",
3397
+ "",
3398
+ "1. Locate the changes in the diff that satisfy it.",
3399
+ "2. Mark it as `met`, `partial`, or `missing`.",
3400
+ "3. Record the specific files / functions / tests that provide evidence.",
3401
+ "",
3402
+ "Also evaluate:",
3403
+ "",
3404
+ "- **Convention compliance** \u2014 PR title uses a conventional commit prefix,",
3405
+ " body includes a closing keyword, branch name follows project conventions",
3406
+ "- **Test coverage** \u2014 new or changed behavior has tests",
3407
+ "- **CI status** \u2014 `gh pr checks` reports all required checks passing",
3408
+ "- **Scope creep** \u2014 diff stays within the issue's stated scope",
3409
+ "",
3410
+ "## Phase 4: Decide and Act",
3411
+ "",
3412
+ "### If all acceptance criteria are met and CI is green",
3413
+ "",
3414
+ "Enable squash auto-merge with branch deletion. This queues the merge to",
3415
+ "happen once required checks pass; no separate approval review is needed.",
3416
+ "",
3417
+ "```bash",
3418
+ "gh pr merge <pr-number> --auto --squash --delete-branch \\",
3419
+ " --subject '<conventional-commit-title>' \\",
3420
+ " --body '<extended-description>'",
3421
+ "```",
3422
+ "",
3423
+ "The squash-merge subject should follow conventional commit format (e.g.",
3424
+ "`feat(scope): description`). The body should bullet the changes and end",
3425
+ "with `Closes #<issue-number>`.",
3426
+ "",
3427
+ "### If any criterion is missing, partial, or CI is failing",
3428
+ "",
3429
+ "Post a plain comment (not a formal review block) with grouped findings:",
3430
+ "",
3431
+ "```bash",
3432
+ "gh pr comment <pr-number> --body '<grouped findings>'",
3433
+ "```",
3434
+ "",
3435
+ "Group findings by severity (**Blocking** / **Suggested** / **Nitpick**).",
3436
+ "For each blocking finding, cite the unmet acceptance criterion and the",
3437
+ "file or function the gap lives in. Do **not** merge, and do **not** push",
3438
+ "any commits to the PR's branch.",
3439
+ "",
3440
+ "Rationale for using a plain comment rather than `gh pr review",
3441
+ "--request-changes`: it is lighter-weight, doesn't require the author to",
3442
+ "dismiss a formal review, and composes cleanly with the multi-PR loop.",
3443
+ "",
3444
+ "## Phase 5: Branch Cleanup and Issue Closure Verification",
3445
+ "",
3446
+ "Auto-merge may not be immediate. Poll the PR state up to 10 times, waiting",
3447
+ "30 seconds between polls:",
3448
+ "",
3449
+ "```bash",
3450
+ "gh pr view <pr-number> --json state --jq '.state'",
3451
+ "```",
3452
+ "",
3453
+ "- **`MERGED`** \u2014 clean up locally **and** verify the linked issue closed:",
3454
+ " ```bash",
3455
+ " git checkout {{repository.defaultBranch}}",
3456
+ " git pull origin {{repository.defaultBranch}}",
3457
+ " git fetch --prune origin",
3458
+ " git branch -d <branch-name> 2>/dev/null || git branch -D <branch-name> 2>/dev/null || true",
3459
+ " ```",
3460
+ " Then check the linked issue state:",
3461
+ " ```bash",
3462
+ " gh issue view <issue-number> --json state --jq '.state'",
3463
+ " ```",
3464
+ " If the issue is **not** `CLOSED`, close it explicitly (this covers",
3465
+ " malformed or missing closing keywords on the merge commit):",
3466
+ " ```bash",
3467
+ " gh issue close <issue-number> --reason completed",
3468
+ " gh issue comment <issue-number> --body 'PR #<pr-number> merged. Closing issue.'",
3469
+ " ```",
3470
+ "- **`CLOSED` (not merged)** \u2014 leave the branch in place; report the closure.",
3471
+ "- **Still `OPEN`** \u2014 auto-merge is pending; report and stop without deleting.",
3472
+ "",
3473
+ "---",
3474
+ "",
3475
+ "## Output Format",
3476
+ "",
3477
+ "Return a structured report:",
3478
+ "",
3479
+ "```",
3480
+ "PR #<number> \u2014 <title>",
3481
+ "Linked issue: #<issue-number>",
3482
+ "Verdict: AUTO_MERGE_ENABLED | NEEDS_CHANGES | INELIGIBLE | BLOCKED",
3483
+ "",
3484
+ "Acceptance criteria:",
3485
+ " [x] <criterion> \u2014 <evidence>",
3486
+ " [~] <criterion> \u2014 partial: <gap>",
3487
+ " [ ] <criterion> \u2014 missing",
3488
+ "",
3489
+ "Findings:",
3490
+ " - Blocking: <items>",
3491
+ " - Suggested: <items>",
3492
+ " - Nitpick: <items>",
3493
+ "",
3494
+ "Action taken: <enable-auto-merge | commented-on-the-pr | none>",
3495
+ "Branch state: <merged | open | closed>",
3496
+ "Issue state: <closed | open>",
3497
+ "```",
3498
+ "",
3499
+ "---",
3500
+ "",
3501
+ "## Rules",
3502
+ "",
3503
+ "1. **One PR per session** when invoked directly (`/review-pr`). When",
3504
+ " invoked from the multi-PR loop (`/review-prs`), process every eligible",
3505
+ " PR in turn.",
3506
+ "2. **Never merge without a linked issue.** If the PR body has no",
3507
+ " `Closes #N` / `Fixes #N` / `Resolves #N`, comment and stop.",
3508
+ "3. **Never merge with failing CI.** Even if every criterion is met,",
3509
+ " block on red checks.",
3510
+ "4. **Never bypass review conventions.** Always use `--squash`, `--auto`,",
3511
+ " and `--delete-branch` for merges. Do not force-merge.",
3512
+ "5. **Do not implement code.** You review, decide, and orchestrate. If",
3513
+ " the PR needs changes, comment and stop.",
3514
+ "6. **Never push commits to the PR's branch.** If the PR needs changes,",
3515
+ " comment and stop \u2014 do not attempt to fix it yourself. The PR author",
3516
+ " owns the branch; pushing to someone else's branch is out of scope.",
3517
+ "7. **In loop mode (`/review-prs`), never stop early.** If any review",
3518
+ " fails, comment and move to the next PR. Only abort the loop on a",
3519
+ " fatal error (e.g. `gh` auth failure, network outage).",
3520
+ "8. **Follow CLAUDE.md conventions** for all `git` and `gh` operations."
3521
+ ].join("\n")
3522
+ };
3523
+ var reviewPrSkill = {
3524
+ name: "review-pr",
3525
+ description: "Review a single pull request against its linked issue's acceptance criteria, then enable squash auto-merge or comment with findings",
3526
+ disableModelInvocation: true,
3527
+ userInvocable: true,
3528
+ context: "fork",
3529
+ agent: "pr-reviewer",
3530
+ platforms: { cursor: { exclude: true } },
3531
+ instructions: [
3532
+ "# Review Pull Request",
3533
+ "",
3534
+ "Run a full PR review against the linked issue's acceptance criteria,",
3535
+ "then either enable squash auto-merge or post a findings comment.",
3536
+ "",
3537
+ "## Usage",
3538
+ "",
3539
+ "/review-pr <pr-number>",
3540
+ "",
3541
+ "## What This Skill Does",
3542
+ "",
3543
+ "1. Runs a pre-flight eligibility filter (mergeable, CI not failing, has linked issue)",
3544
+ "2. Fetches the PR, its diff, CI status, and the linked issue",
3545
+ "3. Builds a checklist from the issue's acceptance criteria",
3546
+ "4. Compares the diff against each criterion",
3547
+ "5. Verifies PR conventions (title, closing keyword, branch name)",
3548
+ "6. Verifies CI is green",
3549
+ "7. **If all checks pass:** enables squash auto-merge (with `--delete-branch`)",
3550
+ "8. **If any check fails:** posts a findings comment via `gh pr comment`",
3551
+ "9. After merge, verifies the linked issue is closed and closes it if not",
3552
+ "10. Cleans up the local branch after merge",
3553
+ "",
3554
+ "## Input",
3555
+ "",
3556
+ "Provide the PR number to review. The skill resolves the linked issue from",
3557
+ "the PR body (`Closes #N` / `Fixes #N` / `Resolves #N`).",
3558
+ "",
3559
+ "## Output",
3560
+ "",
3561
+ "A structured report covering verdict, per-criterion status, findings",
3562
+ "grouped by severity, the action taken, and the final branch / issue state.",
3563
+ "",
3564
+ "## Composability",
3565
+ "",
3566
+ "This skill is generic and can be composed with the `github-workflow`",
3567
+ "bundle. The reviewer never implements code and never pushes to the PR",
3568
+ "branch \u2014 it only reviews, decides, and orchestrates merge or comment."
3569
+ ].join("\n")
3570
+ };
3571
+ var reviewPrsSkill = {
3572
+ name: "review-prs",
3573
+ description: "Loop over every eligible open pull request in the repository and review each one through the full pipeline",
3574
+ disableModelInvocation: true,
3575
+ userInvocable: true,
3576
+ context: "fork",
3577
+ agent: "pr-reviewer",
3578
+ platforms: { cursor: { exclude: true } },
3579
+ instructions: [
3580
+ "# Review All Eligible Pull Requests",
3581
+ "",
3582
+ "Run the pr-reviewer pipeline over every eligible open PR in",
3583
+ "**{{repository.owner}}/{{repository.name}}**, one after another, until",
3584
+ "the eligible queue is empty.",
3585
+ "",
3586
+ "## Usage",
3587
+ "",
3588
+ "/review-prs",
3589
+ "",
3590
+ "## What This Skill Does",
3591
+ "",
3592
+ "### Step 1: Enumerate open PRs",
3593
+ "",
3594
+ "```bash",
3595
+ "gh pr list --json number,title,body,headRefName,mergeable,mergeStateStatus,statusCheckRollup --limit 50",
3596
+ "```",
3597
+ "",
3598
+ "### Step 2: Filter to eligible PRs",
3599
+ "",
3600
+ "A PR is **eligible** when all of the following hold:",
3601
+ "",
3602
+ '1. `state == "OPEN"` (implicit from `gh pr list`).',
3603
+ '2. `mergeable == "MERGEABLE"` (no conflicts).',
3604
+ "3. No required check in `statusCheckRollup` has a failing conclusion",
3605
+ " (`FAILURE`, `TIMED_OUT`, `CANCELLED`, `ERROR`). CI green or still",
3606
+ " pending is fine.",
3607
+ "4. The PR body contains a linked issue (`Closes #N` / `Fixes #N` /",
3608
+ " `Resolves #N`, case-insensitive).",
3609
+ "",
3610
+ "Drop any PR that fails the filter from the queue. Do not comment on",
3611
+ "them from this skill \u2014 the individual `/review-pr` invocation handles",
3612
+ "the inline rejection comment when run on a specific PR.",
3613
+ "",
3614
+ "### Step 3: Process each eligible PR",
3615
+ "",
3616
+ "For every eligible PR, invoke the full pr-reviewer pipeline",
3617
+ "(Phases 1 through 5) as if `/review-pr <number>` had been called",
3618
+ "directly:",
3619
+ "",
3620
+ "- Gather context (diff, checks, linked issue)",
3621
+ "- Compare diff to acceptance criteria",
3622
+ "- Decide and act (enable auto-merge **or** post findings comment)",
3623
+ "- Verify branch / issue cleanup after merge",
3624
+ "",
3625
+ "Continue to the next PR after each one completes. Never stop the loop",
3626
+ "early because a single PR's review failed \u2014 comment and move on.",
3627
+ "",
3628
+ "### Step 4: Stop when the queue is empty",
3629
+ "",
3630
+ "When no eligible PRs remain, emit a final summary listing every PR",
3631
+ "processed and the verdict for each, then stop.",
3632
+ "",
3633
+ "## Output",
3634
+ "",
3635
+ "Per-PR structured report (same shape as `/review-pr`), followed by a",
3636
+ "one-line-per-PR summary at the end:",
3637
+ "",
3638
+ "```",
3639
+ "Summary:",
3640
+ " PR #<n>: <verdict>",
3641
+ " PR #<n>: <verdict>",
3642
+ " ...",
3643
+ "Total processed: <count>",
3644
+ "```",
3645
+ "",
3646
+ "## Failure Handling",
3647
+ "",
3648
+ "Only abort the loop on a fatal error (e.g. `gh` authentication failure,",
3649
+ "network outage). A failed review for an individual PR is not fatal \u2014",
3650
+ "comment on that PR and continue with the next."
3651
+ ].join("\n")
3652
+ };
3653
+ var prReviewBundle = {
3654
+ name: "pr-review",
3655
+ description: "Pull request review workflow: verifies PRs against their linked issues' acceptance criteria and orchestrates squash-merge, single or looped over all eligible PRs",
3656
+ // Default-apply: the PR review workflow is safe to include everywhere,
3657
+ // and keeping review/merge policy centralised in the pr-reviewer agent
3658
+ // means consumers get consistent behaviour out of the box. Consumers can
3659
+ // still exclude it explicitly via `excludeBundles` if desired.
3660
+ appliesWhen: () => true,
3661
+ rules: [
3662
+ {
3663
+ name: "pr-review-workflow",
3664
+ description: "Describes the /review-pr and /review-prs skills and their delegation to the pr-reviewer sub-agent",
3665
+ scope: AGENT_RULE_SCOPE.ALWAYS,
3666
+ content: [
3667
+ "# PR Review Workflow",
3668
+ "",
3669
+ "Two skills are available, both backed by the same `pr-reviewer`",
3670
+ "sub-agent:",
3671
+ "",
3672
+ "- **`/review-pr <pr-number>`** \u2014 review a single targeted PR.",
3673
+ "- **`/review-prs`** \u2014 loop over every eligible open PR in the",
3674
+ " repository and review each one in turn.",
3675
+ "",
3676
+ "The `pr-reviewer` sub-agent:",
3677
+ "",
3678
+ "1. Runs a pre-flight eligibility filter (mergeable, CI not failing,",
3679
+ " has a linked issue). Ineligible PRs get a short comment and are",
3680
+ " skipped.",
3681
+ "2. Fetches the PR, its diff, CI status, and the linked issue",
3682
+ "3. Builds a checklist from the issue's acceptance criteria",
3683
+ "4. Verifies the diff satisfies each criterion and that CI is green",
3684
+ "5. **Enables squash auto-merge** (with `--delete-branch`) when all",
3685
+ " checks pass \u2014 no explicit approval review",
3686
+ "6. **Comments with grouped findings** when any check fails (plain",
3687
+ " `gh pr comment`, not a formal `--request-changes` review)",
3688
+ "7. After a successful merge, verifies the linked issue is closed",
3689
+ " and closes it explicitly if the merge commit did not",
3690
+ "8. Cleans up the local branch after merge",
3691
+ "",
3692
+ "The reviewer **never** implements code and **never** pushes commits",
3693
+ "to a PR's branch \u2014 it only reviews, decides, and orchestrates merge",
3694
+ "or comment. In loop mode, a failed review for one PR never stops",
3695
+ "the loop; the reviewer comments and moves on. See the `pr-reviewer`",
3696
+ "agent definition for the full phase-by-phase contract."
3697
+ ].join("\n"),
3698
+ platforms: {
3699
+ cursor: { exclude: true }
3700
+ },
3701
+ tags: ["workflow"]
3702
+ }
3703
+ ],
3704
+ skills: [reviewPrSkill, reviewPrsSkill],
3705
+ subAgents: [prReviewerSubAgent]
3706
+ };
3707
+
3708
+ // src/agent/bundles/projen.ts
3709
+ var projenBundle = {
3710
+ name: "projen",
3711
+ description: "Projen conventions, synthesis workflow, .projenrc.ts patterns",
3712
+ appliesWhen: (project) => hasDep(project, "projen"),
3713
+ rules: [
3714
+ {
3715
+ name: "development-commands",
3716
+ description: "Projen development commands for building, testing, linting, and validating changes",
3717
+ scope: AGENT_RULE_SCOPE.ALWAYS,
3718
+ content: [
3719
+ "# Development Commands",
3720
+ "",
3721
+ "This project uses Projen to manage configuration and Turborepo to orchestrate builds across the monorepo. Run all commands from the **repository root** unless otherwise noted.",
3722
+ "",
3723
+ "## Synthesizing Projen Configuration",
3724
+ "",
3725
+ "After modifying any file in `projenrc/` or `.projenrc.ts`, regenerate project files:",
3726
+ "",
3727
+ "```sh",
3728
+ "npx projen",
3729
+ "pnpm install",
3730
+ "```",
3731
+ "",
3732
+ "Both steps are required \u2014 `npx projen` regenerates files, `pnpm install` updates the lockfile to match.",
3733
+ "",
3734
+ "## Building",
3735
+ "",
3736
+ "**Full monorepo build** (compile + test + package, all sub-packages via Turborepo):",
3737
+ "",
3738
+ "```sh",
3739
+ "pnpm build:all",
3740
+ "```",
3741
+ "",
3742
+ "**Root project only** (synthesize + compile + lint):",
3743
+ "",
3744
+ "```sh",
3745
+ "pnpm build",
3746
+ "```",
3747
+ "",
3748
+ "**Single sub-package** (compile only):",
3749
+ "",
3750
+ "```sh",
3751
+ "pnpm --filter @codedrifters/<package> compile",
3752
+ "```",
3753
+ "",
3754
+ "Replace `<package>` with `configulator`, `constructs`, or `utils`.",
3755
+ "",
3756
+ "## Testing",
3757
+ "",
3758
+ "**Run tests for a single sub-package:**",
3759
+ "",
3760
+ "```sh",
3761
+ "pnpm --filter @codedrifters/<package> test",
3762
+ "```",
3763
+ "",
3764
+ "This runs ESLint + Vitest for the specified package.",
3765
+ "",
3766
+ "**Run only Vitest (skip lint) in a sub-package:**",
3767
+ "",
3768
+ "```sh",
3769
+ "cd packages/@codedrifters/<package>",
3770
+ "pnpm exec vitest run",
3771
+ "```",
3772
+ "",
3773
+ "**Run a specific test file:**",
3774
+ "",
3775
+ "```sh",
3776
+ "cd packages/@codedrifters/<package>",
3777
+ "pnpm exec vitest run src/path/to/file.test.ts",
3778
+ "```",
3779
+ "",
3780
+ "## Linting",
3781
+ "",
3782
+ "**Lint the root project:**",
3783
+ "",
3784
+ "```sh",
3785
+ "pnpm eslint",
3786
+ "```",
3787
+ "",
3788
+ "**Lint a single sub-package:**",
3789
+ "",
3790
+ "```sh",
3791
+ "pnpm --filter @codedrifters/<package> eslint",
3792
+ "```",
3793
+ "",
3794
+ "## Resetting Build Artifacts",
3795
+ "",
3796
+ "**Reset everything** (all packages + root):",
3797
+ "",
3798
+ "```sh",
3799
+ "pnpm reset:all",
3800
+ "```",
3801
+ "",
3802
+ "**Reset root only:**",
3803
+ "",
3804
+ "```sh",
3805
+ "pnpm reset",
3806
+ "```",
3807
+ "",
3808
+ "## Validating Changes Are Complete",
3809
+ "",
3810
+ "After finishing implementation work, validate that changes are correct by running the appropriate commands depending on what was changed:",
3811
+ "",
3812
+ "1. **Projen config changes** (`projenrc/`, `.projenrc.ts`):",
3813
+ " - Run `npx projen` then `pnpm install`",
3814
+ " - Verify no unexpected generated file changes with `git diff`",
3815
+ "",
3816
+ "2. **Source code changes** (in a sub-package):",
3817
+ " - Compile: `pnpm --filter @codedrifters/<package> compile`",
3818
+ " - Test: `pnpm --filter @codedrifters/<package> test`",
3819
+ "",
3820
+ "3. **Changes spanning multiple packages**:",
3821
+ " - Run `pnpm build:all` to validate the full monorepo build",
3822
+ "",
3823
+ "4. **Root-level changes** (projenrc, root config):",
3824
+ " - Run `pnpm build` to validate root synthesis + compilation + lint",
3825
+ "",
3826
+ "## Command Reference",
3827
+ "",
3828
+ "| Task | Command |",
3829
+ "|------|---------|",
3830
+ "| Synthesize projen | `npx projen` |",
3831
+ "| Install deps | `pnpm install` |",
3832
+ "| Full monorepo build | `pnpm build:all` |",
3833
+ "| Root build only | `pnpm build` |",
3834
+ "| Compile one package | `pnpm --filter @codedrifters/<pkg> compile` |",
3835
+ "| Test one package | `pnpm --filter @codedrifters/<pkg> test` |",
3836
+ "| Lint one package | `pnpm --filter @codedrifters/<pkg> eslint` |",
3837
+ "| Lint root | `pnpm eslint` |",
3838
+ "| Reset all artifacts | `pnpm reset:all` |"
3839
+ ].join("\n"),
3840
+ tags: ["workflow"]
3841
+ },
3842
+ {
3843
+ name: "agent-rules-customization",
3844
+ description: "How to customize agent rules for this repo via the Projen project definition",
3845
+ scope: AGENT_RULE_SCOPE.FILE_PATTERN,
3846
+ filePatterns: [
3847
+ "projenrc/**/*.ts",
3848
+ ".projenrc.ts",
3849
+ ".claude/rules/*.md",
3850
+ ".cursor/rules/*.mdc",
3851
+ "CLAUDE.md"
3852
+ ],
3853
+ content: [
3854
+ "# Customizing Agent Rules",
3855
+ "",
3856
+ "Agent rules for Claude and Cursor are **generated** by configulator's `AgentConfig` component. The generated output files (`.claude/rules/`, `.cursor/rules/`, `CLAUDE.md`) must not be edited directly \u2014 they are overwritten on every `npx projen` run.",
3857
+ "",
3858
+ "## Adding Repo-Specific Rules",
3859
+ "",
3860
+ "Rules that only apply to this repository should be added to the `agentConfig.rules` array in the Projen project definition (`.projenrc.ts` or `projenrc/*.ts`):",
3861
+ "",
3862
+ "```typescript",
3863
+ "agentConfig: {",
3864
+ " rules: [",
3865
+ " {",
3866
+ " name: 'my-repo-rule',",
3867
+ " description: 'What this rule does',",
3868
+ " scope: AGENT_RULE_SCOPE.ALWAYS, // or FILE_PATTERN with filePatterns",
3869
+ " content: '# My Rule\\n\\n- Guideline 1\\n- Guideline 2',",
3870
+ " },",
3871
+ " ],",
3872
+ "}",
3873
+ "```",
3874
+ "",
3875
+ "## Extending Existing Bundle Rules",
3876
+ "",
3877
+ "To append repo-specific content to a rule provided by a configulator bundle (without replacing it), use `agentConfig.ruleExtensions`:",
3878
+ "",
3879
+ "```typescript",
3880
+ "agentConfig: {",
3881
+ " ruleExtensions: {",
3882
+ " 'typescript-conventions': '## Additional Guidelines\\n\\n- My custom guideline',",
3883
+ " },",
3884
+ "}",
3885
+ "```",
3886
+ "",
3887
+ "## After Any Change",
3888
+ "",
3889
+ "Run `npx projen` then `pnpm install` to regenerate the output files."
3890
+ ].join("\n"),
3891
+ tags: ["workflow"]
3892
+ },
3893
+ {
3894
+ name: "projen-conventions",
3895
+ description: "Projen configuration patterns and best practices",
3896
+ scope: AGENT_RULE_SCOPE.FILE_PATTERN,
3897
+ filePatterns: ["projenrc/**/*.ts", ".projenrc.ts"],
3898
+ content: [
3899
+ "# Projen Conventions",
3900
+ "",
3901
+ "## Configuration Management",
3902
+ "",
3903
+ "- **Never edit generated files** (`package.json`, `tsconfig.json`, etc. marked with `// ~~ Generated by projen`)",
3904
+ "- Edit Projen configuration in:",
3905
+ " - `.projenrc.ts` (root)",
3906
+ " - `projenrc/*.ts` (package-specific)",
3907
+ "- After making Projen changes, run `npx projen` to synthesize",
3908
+ "",
3909
+ "## Workspace Dependencies",
3910
+ "",
3911
+ "When adding dependencies between packages in a monorepo:",
3912
+ "",
3913
+ '- Use the workspace protocol: `project.addDeps("@org/sibling-pkg@workspace:*")`',
3914
+ "- This ensures the local version is always resolved, not a registry version",
3915
+ '- For dev dependencies: `project.addDevDeps("@org/sibling-pkg@workspace:*")`',
3916
+ "",
3917
+ "## The `configureMyProject` Pattern",
3918
+ "",
3919
+ "Each package should expose a `configureMyProject(options)` factory function that creates and configures its Projen project:",
3920
+ "",
3921
+ "```typescript",
3922
+ "export function configureMyProject(",
3923
+ " options: MyProjectOptions,",
3924
+ "): TypeScriptProject {",
3925
+ " const project = new TypeScriptProject({",
3926
+ " ...options,",
3927
+ " // package-specific defaults",
3928
+ " });",
3929
+ "",
3930
+ " // Attach components, configure rules, etc.",
3931
+ " return project;",
3932
+ "}",
3933
+ "```",
3934
+ "",
3935
+ "This pattern keeps `.projenrc.ts` clean and makes package configuration reusable and testable.",
3936
+ "",
3937
+ "## Custom Projen Components",
3938
+ "",
3939
+ "All custom components must extend `Component` from Projen and use a static `.of()` factory for discovery:",
3940
+ "",
3941
+ "```typescript",
3942
+ "export class MyComponent extends Component {",
3943
+ " public static of(project: Project): MyComponent | undefined {",
3944
+ " const isDefined = (c: Component): c is MyComponent =>",
3945
+ " c instanceof MyComponent;",
3946
+ " return project.components.find(isDefined);",
3947
+ " }",
3948
+ "",
3949
+ " constructor(project: Project, options: MyComponentOptions) {",
3950
+ " super(project);",
3951
+ " // Implementation",
3952
+ " }",
3953
+ "}",
3954
+ "```",
3955
+ "",
3956
+ "## Component Authoring",
3957
+ "",
3958
+ "- Export project types and utilities from `index.ts`",
3959
+ "- Follow Projen's component lifecycle patterns",
3960
+ "- Use `merge` from `ts-deepmerge` for deep merging configuration objects",
3961
+ "- Components should be reusable and configurable; use TypeScript interfaces for component options",
3962
+ "- Provide sensible defaults while allowing customization",
3963
+ "- Document public APIs with minimal JSDoc; put extended documentation in markdown",
3964
+ "",
3965
+ "## Dependencies",
3966
+ "",
3967
+ "- Dependencies managed through Projen configuration, not directly in `package.json`",
3968
+ '- Use catalog dependencies when available (e.g., `"projen": "catalog:"`)',
3969
+ "- Peer dependencies for shared libraries (e.g., `constructs`, `projen`, `aws-cdk-lib`)",
3970
+ '- Use workspace protocol for internal packages: `"@org/pkg@workspace:*"`'
3971
+ ].join("\n"),
3972
+ tags: ["workflow"]
3973
+ }
3974
+ ]
3975
+ };
3976
+
3977
+ // src/agent/bundles/requirements-analyst.ts
3978
+ var requirementsAnalystSubAgent = {
3979
+ name: "requirements-analyst",
3980
+ description: "Discovers requirement gaps from BCM model docs, competitive analysis, product docs, and meeting extracts. Produces scan reports and proposals for the downstream requirements-writer agent. Runs through a 3-phase pipeline (scan \u2192 draft \u2192 trace), one phase per session, tracked by req:* GitHub issue labels.",
3981
+ model: AGENT_MODEL.POWERFUL,
3982
+ maxTurns: 80,
3983
+ platforms: { cursor: { exclude: true } },
3984
+ prompt: [
3985
+ "# Requirements Analyst Agent",
3986
+ "",
3987
+ "Dedicated agent loop for discovering requirement gaps from BCM (Business",
3988
+ "Capability Model) documents, product docs, and competitive analysis \u2014 then",
3989
+ "creating well-formed requirement issues for the downstream",
3990
+ "requirements-writer (BCM writer) agent to draft. Designed for scheduled",
3991
+ "execution downstream of the BCM writer and company research agents.",
3992
+ "",
3993
+ "Follow your project's shared agent conventions (`AGENTS.md`,",
3994
+ "`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
3995
+ "",
3996
+ "---",
3997
+ "",
3998
+ ...PROJECT_CONTEXT_MAINTAINER_SECTION,
3999
+ "## Design Principles",
4000
+ "",
4001
+ "1. **Discover, don't write.** This agent identifies *what requirements are",
4002
+ " missing*. The requirements-writer skill writes the actual documents. The",
4003
+ " boundary keeps this agent fast and the requirements-writer authoritative.",
4004
+ "2. **Trace everything.** Every discovered gap links to the source that",
4005
+ " revealed it (a BCM model doc, competitive analysis, product doc, or",
4006
+ " meeting extract).",
4007
+ "3. **Respect the taxonomy.** Route every discovered requirement to the",
4008
+ " correct BCM category (FR, BR, NFR, SEC, DR, INT, OPS, UX, MT, ADR, TR)",
4009
+ " using the disambiguation rules in the requirements-writer skill.",
4010
+ "4. **Deduplicate.** Before creating an issue, check whether a requirement",
4011
+ " already exists or an issue is already open for it.",
4012
+ "",
4013
+ "---",
4014
+ "",
4015
+ "## State Machine Overview",
4016
+ "",
4017
+ "Requirements synthesis flows through **3 phases**:",
4018
+ "",
4019
+ "```",
4020
+ "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
4021
+ "\u2502 1. SCAN \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 2. DRAFT \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 3. TRACE \u2502",
4022
+ "\u2502 Read docs, \u2502 \u2502 Write gap \u2502 \u2502 Create GH \u2502",
4023
+ "\u2502 identify \u2502 \u2502 report with \u2502 \u2502 issues and \u2502",
4024
+ "\u2502 gaps, check \u2502 \u2502 requirement \u2502 \u2502 update src \u2502",
4025
+ "\u2502 for dupes \u2502 \u2502 proposals \u2502 \u2502 docs with \u2502",
4026
+ "\u2502 \u2502 \u2502 \u2502 \u2502 traceability\u2502",
4027
+ "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
4028
+ "```",
4029
+ "",
4030
+ "**Issue labels encode the phase:**",
4031
+ "",
4032
+ "| Label | Phase | Session work |",
4033
+ "|-------|-------|-------------|",
4034
+ "| `req:scan` | 1. Scan | Read source docs, identify potential requirement gaps, check against existing requirements and open issues, write deduplicated scan report |",
4035
+ "| `req:draft` | 2. Draft | Write gap report with proposed requirements |",
4036
+ "| `req:trace` | 3. Trace | Create GitHub issues for each proposed requirement and update source documents with traceability notes |",
4037
+ "",
4038
+ "All issues also carry `type:requirement` and a `status:*` label.",
4039
+ "",
4040
+ "**Issue count per scan cycle:** 1 scan + 1 draft + 1 trace = **3 sessions**.",
4041
+ "",
4042
+ "**Shortened paths:**",
4043
+ "- No gaps found after scan \u2192 skip draft and trace \u2192 **1 session**",
4044
+ "- No source docs need traceability updates \u2192 still **3 sessions** (trace",
4045
+ " handles both issue creation and doc updates)",
4046
+ "",
4047
+ "---",
4048
+ "",
4049
+ "## Configurable Paths",
4050
+ "",
4051
+ "Projects adopting this bundle must define these paths in their agent",
4052
+ "configuration (`agentConfig.rules` extension or project-level docs):",
4053
+ "",
4054
+ "| Placeholder | Meaning | Typical value |",
4055
+ "|-------------|---------|---------------|",
4056
+ "| `<BCM_DOCS_ROOT>` | Root of BCM model docs (capability models) | `src/content/docs/concepts/` |",
4057
+ "| `<COMPETITIVE_ROOT>` | Competitive analysis docs | `src/content/docs/business-strategy/competitive/` |",
4058
+ "| `<PRODUCT_ROOT>` | Product roadmap / entity taxonomy | `src/content/docs/product/` |",
4059
+ "| `<MEETINGS_ROOT>` | Meeting extracts | `src/content/docs/research/meetings/` |",
4060
+ "| `<RESEARCH_REQUIREMENTS_ROOT>` | Scan reports and proposals | `src/content/docs/research/requirements/` |",
4061
+ "| `<REQUIREMENTS_ROOT>` | Final requirement documents (owned by requirements-writer) | `src/content/docs/requirements/` |",
4062
+ "| `<PREFIX>` | Project-specific requirement ID prefix | e.g. `VRTX`, `ACME` |",
4063
+ "",
4064
+ "If your project stores these in different locations, substitute accordingly",
4065
+ "wherever the phase instructions reference a path.",
4066
+ "",
4067
+ "---",
4068
+ "",
4069
+ "## Agent Loop",
4070
+ "",
4071
+ "Run this loop exactly once per session. Never start a second issue.",
4072
+ "",
4073
+ "1. Claim one open `type:requirement` issue using phase priority:",
4074
+ " `req:scan` > `req:draft` > `req:trace`.",
4075
+ "2. Transition `status:ready` \u2192 `status:in-progress` and create the branch",
4076
+ " per your project's branch-naming convention.",
4077
+ "3. Execute the phase handler that matches the issue's `req:*` label.",
4078
+ "4. Commit, push, open a PR (if applicable), and close the issue per your",
4079
+ " project's PR workflow.",
4080
+ "",
4081
+ "---",
4082
+ "",
4083
+ "## Phase 1: Scan (`req:scan`)",
4084
+ "",
4085
+ "**Goal:** Read source documents, identify where requirements are missing,",
4086
+ "incomplete, or contradictory, then check each potential gap against existing",
4087
+ "requirements and open issues to eliminate duplicates. Produces a single",
4088
+ "deduplicated scan report.",
4089
+ "",
4090
+ "**Budget:** Reading source docs + reading requirement registries + searching",
4091
+ "issues. Write one deduplicated scan output file.",
4092
+ "",
4093
+ "### Scan Sources",
4094
+ "",
4095
+ "The issue specifies which source(s) to scan. Common scan scopes:",
4096
+ "",
4097
+ "| Scope | What to read | What to look for |",
4098
+ "|-------|-------------|-----------------|",
4099
+ "| **BCM model doc** | One `{PREFIX}-NNN` doc under `<BCM_DOCS_ROOT>` | The doc's project-relevance section (commonly `## <Project> Relevance` or `## Strategic Implications`) \u2014 gaps where capabilities exist but no FR/BR/INT addresses them. Use `docs/project-context.md` to judge what is relevant. |",
4100
+ "| **Competitive analysis** | One `comp-*.md` doc under `<COMPETITIVE_ROOT>` | Feature comparison gaps \u2014 competitor features the product lacks requirements for |",
4101
+ "| **Product roadmap** | `<PRODUCT_ROOT>/prioritized-feature-roadmap.md` | Roadmap items without corresponding FRs |",
4102
+ "| **Entity taxonomy** | `<PRODUCT_ROOT>/entity-taxonomy.md` | Entities without CRUD requirements (FR), data requirements (DR), or security requirements (SEC) |",
4103
+ "| **Meeting extract** | `<MEETINGS_ROOT>/meeting-*.extract.md` | Requirements identified but not yet formalized |",
4104
+ "",
4105
+ "### Steps",
4106
+ "",
4107
+ "1. **Read the source documents** specified in the issue.",
4108
+ "",
4109
+ "2. **Identify potential gaps.** For each potential missing requirement:",
4110
+ " - Classify into the correct BCM category (FR, BR, NFR, SEC, DR, INT,",
4111
+ " OPS, UX, MT, ADR, TR)",
4112
+ " - Apply the disambiguation rules from the requirements-writer skill",
4113
+ " - Note the source that revealed the gap",
4114
+ " - Estimate priority based on the source context",
4115
+ "",
4116
+ "3. **Read the requirements registry.** Scan `_index.md` files in each",
4117
+ " `<REQUIREMENTS_ROOT>/<category>/` directory to know what already exists.",
4118
+ "",
4119
+ "4. **Search for existing issues.** For each potential gap, search open issues:",
4120
+ " ```bash",
4121
+ ' gh issue list --label "type:requirement" --state open \\',
4122
+ " --json number,title --limit 100",
4123
+ " ```",
4124
+ "",
4125
+ "5. **Classify each gap:**",
4126
+ " - **New** \u2014 no existing requirement or open issue covers this",
4127
+ " - **Duplicate** \u2014 an existing requirement already addresses this",
4128
+ " - **In progress** \u2014 an open issue already targets this",
4129
+ " - **Partial** \u2014 existing requirement partially covers this; note the gap",
4130
+ "",
4131
+ "6. **Write the deduplicated scan report** to:",
4132
+ " ```",
4133
+ " <RESEARCH_REQUIREMENTS_ROOT>/req-scan-<scope>-<YYYY-MM-DD>.md",
4134
+ " ```",
4135
+ "",
4136
+ " Format:",
4137
+ " ```markdown",
4138
+ " ---",
4139
+ ' title: "Requirements Scan: <scope>"',
4140
+ " date: YYYY-MM-DD",
4141
+ " parent_issue: <N>",
4142
+ " status: complete",
4143
+ " ---",
4144
+ "",
4145
+ " # Requirements Scan: <scope>",
4146
+ "",
4147
+ " ## Source Documents Reviewed",
4148
+ " - <path> \u2014 <brief description>",
4149
+ "",
4150
+ " ## Existing Requirements Checked",
4151
+ " - <category>: <count> existing docs, <count> open issues",
4152
+ "",
4153
+ " ## Identified Gaps (New)",
4154
+ " ### Gap 1: <Title>",
4155
+ " - **Category:** FR / BR / NFR / SEC / DR / INT / OPS / UX / MT / ADR / TR",
4156
+ " - **Source:** <path to doc + section that revealed this gap>",
4157
+ " - **Priority:** High / Normal / Low",
4158
+ " - **Rationale:** <why this requirement is needed>",
4159
+ " - **Duplicate check:** No existing requirement or open issue found",
4160
+ " - **Proposed scope:** <1-2 sentences on what the requirement should cover>",
4161
+ "",
4162
+ " ## Already Covered",
4163
+ " <list of potential gaps that turned out to already have requirements>",
4164
+ "",
4165
+ " ## In Progress",
4166
+ " <gaps that already have open issues \u2014 include issue numbers>",
4167
+ "",
4168
+ " ## Ambiguous / Needs Human Decision",
4169
+ " <gaps where the correct category or scope is unclear>",
4170
+ " ```",
4171
+ "",
4172
+ "7. **Create downstream issues based on findings:**",
4173
+ " - If any new gaps were identified \u2192 create `req:draft` issue",
4174
+ " (blocked on this issue via `Depends on: #N`).",
4175
+ " - If **no gaps** were found \u2192 stop (no further phases needed). Comment",
4176
+ " on the issue noting that no gaps were identified, and proceed directly",
4177
+ " to commit and push. The scan issue will be marked done with no",
4178
+ " downstream work needed.",
4179
+ "",
4180
+ "8. **Commit and push.**",
4181
+ "",
4182
+ "---",
4183
+ "",
4184
+ "## Phase 2: Draft (`req:draft`)",
4185
+ "",
4186
+ "**Goal:** Expand each identified gap into a requirement proposal with enough",
4187
+ "detail for the requirements-writer to produce a full document.",
4188
+ "",
4189
+ "**Budget:** No web searches. Reading + writing.",
4190
+ "",
4191
+ "### Steps",
4192
+ "",
4193
+ "1. **Read the scan report** from Phase 1.",
4194
+ "",
4195
+ "2. **For each gap**, write a detailed proposal:",
4196
+ "",
4197
+ " ```markdown",
4198
+ " ## Proposed: <PREFIX>-<NNN> \u2014 <Title>",
4199
+ "",
4200
+ " **Category:** <FR/BR/NFR/SEC/DR/INT/OPS/UX/MT/ADR/TR>",
4201
+ " **Priority:** <High/Normal/Low>",
4202
+ " **Source:** <document path and section>",
4203
+ "",
4204
+ " ### Summary",
4205
+ " <2-3 sentences describing what the requirement should capture>",
4206
+ "",
4207
+ " ### Draft Acceptance Criteria",
4208
+ " - [ ] <testable criterion 1>",
4209
+ " - [ ] <testable criterion 2>",
4210
+ " - [ ] <testable criterion 3>",
4211
+ "",
4212
+ " ### Traceability",
4213
+ " - **Implements:** <BR or parent requirement if applicable>",
4214
+ " - **Related:** <existing requirements that interact with this one>",
4215
+ " - **Source:** <BCM doc, competitive analysis, or meeting that revealed",
4216
+ " the gap \u2014 use a markdown link. If the source is a meeting note, the",
4217
+ " downstream requirement doc must include the same meeting as a link in",
4218
+ " its Traceability `Related:` list.>",
4219
+ "",
4220
+ " ### Decision Authority",
4221
+ ' <"Direct write" for BR/FR/NFR/SEC/UX, or "Proposed \u2014 needs human',
4222
+ ' decision" for ADR/TR, or "Mixed \u2014 defer technology choices" for',
4223
+ " DR/MT/INT/OPS>",
4224
+ "",
4225
+ " ### Notes for Requirements Writer",
4226
+ " <any context the writer should know \u2014 related ADRs, existing partial",
4227
+ " coverage, relevant competitive features>",
4228
+ " ```",
4229
+ "",
4230
+ "3. **Write the proposals** to:",
4231
+ " ```",
4232
+ " <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<YYYY-MM-DD>.md",
4233
+ " ```",
4234
+ "",
4235
+ "4. **Determine next sequence numbers.** Check each target category",
4236
+ " directory under `<REQUIREMENTS_ROOT>/<category>/` to find the next",
4237
+ " available `NNN` for each proposed requirement.",
4238
+ "",
4239
+ "5. **Create the `req:trace` issue** blocked on this draft issue.",
4240
+ "",
4241
+ "6. **Commit and push.**",
4242
+ "",
4243
+ "---",
4244
+ "",
4245
+ "## Phase 3: Trace (`req:trace`)",
4246
+ "",
4247
+ "**Goal:** Create GitHub issues for each proposed requirement and update",
4248
+ "source documents with traceability notes indicating that requirement issues",
4249
+ "were created.",
4250
+ "",
4251
+ "**Budget:** No web searches. Issue creation + minor edits to source",
4252
+ "documents.",
4253
+ "",
4254
+ "### Steps",
4255
+ "",
4256
+ "1. **Read the proposals** from Phase 2.",
4257
+ "",
4258
+ "2. **Create requirement issues.** For each proposal:",
4259
+ "",
4260
+ " All `type:requirement` issues default to `priority:medium` (override",
4261
+ " only if the proposal's priority was explicitly High or Low).",
4262
+ "",
4263
+ " ```bash",
4264
+ " gh issue create \\",
4265
+ ' --title "docs(<category>): <PREFIX>-<NNN> \u2014 <title>" \\',
4266
+ ' --label "type:requirement" --label "status:ready" --label "priority:medium" \\',
4267
+ ' --body "## Objective',
4268
+ " Write <PREFIX>-<NNN> \u2014 <title>.",
4269
+ "",
4270
+ " ## Context",
4271
+ " - **Gap identified by:** requirements scan of <source>",
4272
+ " - **Proposals file:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md",
4273
+ "",
4274
+ " ## Inputs",
4275
+ " - **Depends on:** (none)",
4276
+ " - **Read:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md, <source docs>",
4277
+ "",
4278
+ " ## Acceptance Criteria",
4279
+ " - [ ] Requirement document follows <category> template",
4280
+ " - [ ] Traceability links to source BCM/competitive/product doc",
4281
+ " - [ ] Registry index updated",
4282
+ " - [ ] Decision authority rules followed (direct write vs. proposed)",
4283
+ "",
4284
+ " ## Scope Size",
4285
+ " small",
4286
+ "",
4287
+ " ## Output Path",
4288
+ ' <REQUIREMENTS_ROOT>/<category>/<PREFIX>-<NNN>-<slug>.md"',
4289
+ " ```",
4290
+ "",
4291
+ "3. **Update source documents.** In each BCM model doc or competitive",
4292
+ " analysis that was scanned, add a note in the project-relevance /",
4293
+ " strategic-implications section (whichever heading the source doc uses)",
4294
+ " indicating that a requirement issue was created:",
4295
+ "",
4296
+ " ```markdown",
4297
+ " - Gap addressed: see [<PREFIX>-<NNN>](<relative path to requirement doc>)",
4298
+ " (issue #<N>)",
4299
+ " ```",
4300
+ "",
4301
+ "4. **Comment on the scan issue** with a summary of all issues created and",
4302
+ " all docs updated.",
4303
+ "",
4304
+ "5. **Commit and push.**",
4305
+ "",
4306
+ "---",
4307
+ "",
4308
+ "## Coordination with Other Agents",
4309
+ "",
4310
+ "| Direction | Agent | What |",
4311
+ "|-----------|-------|------|",
4312
+ "| Upstream | BCM Writer | Scans capability-model docs for project-relevance gaps (judged against `docs/project-context.md`) |",
4313
+ "| Upstream | Company Research | Scans competitive analysis for feature comparison gaps |",
4314
+ "| Upstream | Meeting Analyst | Scans meeting extracts for requirement proposals |",
4315
+ "| Downstream | Requirements Writer (BCM Writer) | Creates `type:requirement` issues for the skill to draft |",
4316
+ "",
4317
+ "**File boundaries:** Writes to `<RESEARCH_REQUIREMENTS_ROOT>/req-*.md` and",
4318
+ "minor traceability edits to `<BCM_DOCS_ROOT>` and `<COMPETITIVE_ROOT>`.",
4319
+ "Never writes to `<REQUIREMENTS_ROOT>/` \u2014 that is owned by the",
4320
+ "requirements-writer agent.",
4321
+ "",
4322
+ "---",
4323
+ "",
4324
+ "## Blocked Issues",
4325
+ "",
4326
+ "Additional block reasons specific to requirements synthesis:",
4327
+ "- Source document has unresolved contradictions",
4328
+ "- Category classification is ambiguous (needs human disambiguation)",
4329
+ "- Dependent BCM documents are still in draft with placeholder content",
4330
+ "",
4331
+ "---",
4332
+ "",
4333
+ "## Rules",
4334
+ "",
4335
+ "- **Discover, don't write requirements.** Create issues for the",
4336
+ " requirements-writer \u2014 don't write requirement documents directly.",
4337
+ "- **Deduplicate rigorously.** Check both existing docs and open issues",
4338
+ " before flagging a gap.",
4339
+ "- **Respect decision authority.** Mark ADR/TR proposals as needing human",
4340
+ " decision. Don't create direct-write issues for technology choices.",
4341
+ "- **Bidirectional traceability.** Every `req-scan-*.md` and",
4342
+ " `req-proposals-*.md` must include a `## Produced` section listing the",
4343
+ " downstream requirement issues (and eventual requirement documents) it",
4344
+ " spawned, as markdown links; each formal requirement document under",
4345
+ " `<REQUIREMENTS_ROOT>/` must include a forward link back to the scan or",
4346
+ " proposal that produced it."
4347
+ ].join("\n")
4348
+ };
4349
+ var scanRequirementsSkill = {
4350
+ name: "scan-requirements",
4351
+ description: "Kick off a requirements-analyst scan across BCM model docs, competitive analysis, product docs, or meeting extracts. Creates a req:scan issue and dispatches Phase 1.",
4352
+ disableModelInvocation: true,
4353
+ userInvocable: true,
4354
+ context: "fork",
4355
+ agent: "requirements-analyst",
4356
+ platforms: { cursor: { exclude: true } },
4357
+ instructions: [
4358
+ "# Scan Requirements",
4359
+ "",
4360
+ "Kick off a requirements-analyst scan cycle. Creates a `req:scan` issue",
4361
+ "targeted at the requested scope and dispatches Phase 1 (Scan) in the",
4362
+ "requirements-analyst agent.",
4363
+ "",
4364
+ "## Usage",
4365
+ "",
4366
+ "/scan-requirements <scope>",
4367
+ "",
4368
+ "Where `<scope>` is one of:",
4369
+ "- `bcm:<PREFIX-NNN>` \u2014 a single BCM model doc",
4370
+ "- `competitive:<slug>` \u2014 a single competitive analysis doc",
4371
+ "- `product-roadmap` \u2014 the prioritized feature roadmap",
4372
+ "- `entity-taxonomy` \u2014 the entity taxonomy doc",
4373
+ "- `meeting:<slug>` \u2014 a meeting extract",
4374
+ "- `all-bcm` / `all-competitive` \u2014 full sweep (long-running)",
4375
+ "",
4376
+ "## Steps",
4377
+ "",
4378
+ "1. Create a `req:scan` issue with `type:requirement`, `priority:medium`,",
4379
+ " and `status:ready`. Body must list the files to read and the scan scope.",
4380
+ "2. Execute Phase 1 (Scan) of the requirements-analyst agent.",
4381
+ "3. If gaps are found, a `req:draft` issue is created automatically.",
4382
+ "",
4383
+ "## Output",
4384
+ "",
4385
+ "- A `req-scan-<scope>-<YYYY-MM-DD>.md` file under the project's research",
4386
+ " requirements directory.",
4387
+ "- A `req:draft` issue if any gaps were identified."
4388
+ ].join("\n")
4389
+ };
4390
+ var requirementsAnalystBundle = {
4391
+ name: "requirements-analyst",
4392
+ description: "Requirements gap-discovery agent bundle for BCM-driven projects. 3-phase pipeline (scan, draft, trace) with req:* phase labels.",
4393
+ appliesWhen: () => true,
4394
+ rules: [
3293
4395
  {
3294
- name: "agent-rules-customization",
3295
- description: "How to customize agent rules for this repo via the Projen project definition",
3296
- scope: AGENT_RULE_SCOPE.FILE_PATTERN,
3297
- filePatterns: [
3298
- "projenrc/**/*.ts",
3299
- ".projenrc.ts",
3300
- ".claude/rules/*.md",
3301
- ".cursor/rules/*.mdc",
3302
- "CLAUDE.md"
3303
- ],
4396
+ name: "requirements-analyst-workflow",
4397
+ description: "Describes the 3-phase requirements gap-discovery pipeline, the req:* label taxonomy, and the boundary with the downstream requirements-writer agent.",
4398
+ scope: AGENT_RULE_SCOPE.ALWAYS,
3304
4399
  content: [
3305
- "# Customizing Agent Rules",
3306
- "",
3307
- "Agent rules for Claude and Cursor are **generated** by configulator's `AgentConfig` component. The generated output files (`.claude/rules/`, `.cursor/rules/`, `CLAUDE.md`) must not be edited directly \u2014 they are overwritten on every `npx projen` run.",
3308
- "",
3309
- "## Adding Repo-Specific Rules",
3310
- "",
3311
- "Rules that only apply to this repository should be added to the `agentConfig.rules` array in the Projen project definition (`.projenrc.ts` or `projenrc/*.ts`):",
3312
- "",
3313
- "```typescript",
3314
- "agentConfig: {",
3315
- " rules: [",
3316
- " {",
3317
- " name: 'my-repo-rule',",
3318
- " description: 'What this rule does',",
3319
- " scope: AGENT_RULE_SCOPE.ALWAYS, // or FILE_PATTERN with filePatterns",
3320
- " content: '# My Rule\\n\\n- Guideline 1\\n- Guideline 2',",
3321
- " },",
3322
- " ],",
3323
- "}",
3324
- "```",
3325
- "",
3326
- "## Extending Existing Bundle Rules",
3327
- "",
3328
- "To append repo-specific content to a rule provided by a configulator bundle (without replacing it), use `agentConfig.ruleExtensions`:",
4400
+ "# Requirements Analyst Workflow",
3329
4401
  "",
3330
- "```typescript",
3331
- "agentConfig: {",
3332
- " ruleExtensions: {",
3333
- " 'typescript-conventions': '## Additional Guidelines\\n\\n- My custom guideline',",
3334
- " },",
3335
- "}",
3336
- "```",
4402
+ "Use `/scan-requirements <scope>` to kick off a requirements gap",
4403
+ "discovery cycle. The pipeline runs in 3 phases \u2014 scan, draft, trace \u2014",
4404
+ "each tracked by its own GitHub issue labeled `req:scan`, `req:draft`,",
4405
+ "or `req:trace`. All issues carry `type:requirement`.",
3337
4406
  "",
3338
- "## After Any Change",
4407
+ "The requirements-analyst *discovers gaps and drafts proposals*; it",
4408
+ "does **not** write final requirement documents. Writing is the job of",
4409
+ "the downstream requirements-writer (BCM writer) agent. Keep that",
4410
+ "boundary clean: proposals land under the research requirements",
4411
+ "directory, not under the authoritative requirements tree.",
3339
4412
  "",
3340
- "Run `npx projen` then `pnpm install` to regenerate the output files."
4413
+ "See the `requirements-analyst` agent definition for full workflow",
4414
+ "details and phase-by-phase instructions."
3341
4415
  ].join("\n"),
4416
+ platforms: {
4417
+ cursor: { exclude: true }
4418
+ },
3342
4419
  tags: ["workflow"]
4420
+ }
4421
+ ],
4422
+ skills: [scanRequirementsSkill],
4423
+ subAgents: [requirementsAnalystSubAgent],
4424
+ labels: [
4425
+ {
4426
+ name: "type:requirement",
4427
+ color: "1D76DB",
4428
+ description: "Work that produces or discovers a requirement document (FR, BR, NFR, etc.)"
3343
4429
  },
3344
4430
  {
3345
- name: "projen-conventions",
3346
- description: "Projen configuration patterns and best practices",
3347
- scope: AGENT_RULE_SCOPE.FILE_PATTERN,
3348
- filePatterns: ["projenrc/**/*.ts", ".projenrc.ts"],
3349
- content: [
3350
- "# Projen Conventions",
3351
- "",
3352
- "## Configuration Management",
3353
- "",
3354
- "- **Never edit generated files** (`package.json`, `tsconfig.json`, etc. marked with `// ~~ Generated by projen`)",
3355
- "- Edit Projen configuration in:",
3356
- " - `.projenrc.ts` (root)",
3357
- " - `projenrc/*.ts` (package-specific)",
3358
- "- After making Projen changes, run `npx projen` to synthesize",
3359
- "",
3360
- "## Workspace Dependencies",
3361
- "",
3362
- "When adding dependencies between packages in a monorepo:",
3363
- "",
3364
- '- Use the workspace protocol: `project.addDeps("@org/sibling-pkg@workspace:*")`',
3365
- "- This ensures the local version is always resolved, not a registry version",
3366
- '- For dev dependencies: `project.addDevDeps("@org/sibling-pkg@workspace:*")`',
3367
- "",
3368
- "## The `configureMyProject` Pattern",
3369
- "",
3370
- "Each package should expose a `configureMyProject(options)` factory function that creates and configures its Projen project:",
3371
- "",
3372
- "```typescript",
3373
- "export function configureMyProject(",
3374
- " options: MyProjectOptions,",
3375
- "): TypeScriptProject {",
3376
- " const project = new TypeScriptProject({",
3377
- " ...options,",
3378
- " // package-specific defaults",
3379
- " });",
3380
- "",
3381
- " // Attach components, configure rules, etc.",
3382
- " return project;",
3383
- "}",
3384
- "```",
3385
- "",
3386
- "This pattern keeps `.projenrc.ts` clean and makes package configuration reusable and testable.",
3387
- "",
3388
- "## Custom Projen Components",
3389
- "",
3390
- "All custom components must extend `Component` from Projen and use a static `.of()` factory for discovery:",
3391
- "",
3392
- "```typescript",
3393
- "export class MyComponent extends Component {",
3394
- " public static of(project: Project): MyComponent | undefined {",
3395
- " const isDefined = (c: Component): c is MyComponent =>",
3396
- " c instanceof MyComponent;",
3397
- " return project.components.find(isDefined);",
3398
- " }",
3399
- "",
3400
- " constructor(project: Project, options: MyComponentOptions) {",
3401
- " super(project);",
3402
- " // Implementation",
3403
- " }",
3404
- "}",
3405
- "```",
3406
- "",
3407
- "## Component Authoring",
3408
- "",
3409
- "- Export project types and utilities from `index.ts`",
3410
- "- Follow Projen's component lifecycle patterns",
3411
- "- Use `merge` from `ts-deepmerge` for deep merging configuration objects",
3412
- "- Components should be reusable and configurable; use TypeScript interfaces for component options",
3413
- "- Provide sensible defaults while allowing customization",
3414
- "- Document public APIs with minimal JSDoc; put extended documentation in markdown",
3415
- "",
3416
- "## Dependencies",
3417
- "",
3418
- "- Dependencies managed through Projen configuration, not directly in `package.json`",
3419
- '- Use catalog dependencies when available (e.g., `"projen": "catalog:"`)',
3420
- "- Peer dependencies for shared libraries (e.g., `constructs`, `projen`, `aws-cdk-lib`)",
3421
- '- Use workspace protocol for internal packages: `"@org/pkg@workspace:*"`'
3422
- ].join("\n"),
3423
- tags: ["workflow"]
4431
+ name: "req:scan",
4432
+ color: "C5DEF5",
4433
+ description: "Phase 1: scan source docs for requirement gaps and deduplicate"
4434
+ },
4435
+ {
4436
+ name: "req:draft",
4437
+ color: "BFDADC",
4438
+ description: "Phase 2: draft requirement proposals for the requirements-writer"
4439
+ },
4440
+ {
4441
+ name: "req:trace",
4442
+ color: "D4C5F9",
4443
+ description: "Phase 3: create requirement issues and backfill traceability on source docs"
3424
4444
  }
3425
4445
  ]
3426
4446
  };
3427
4447
 
3428
- // src/agent/bundles/requirements-analyst.ts
3429
- var requirementsAnalystSubAgent = {
3430
- name: "requirements-analyst",
3431
- description: "Discovers requirement gaps from BCM model docs, competitive analysis, product docs, and meeting extracts. Produces scan reports and proposals for the downstream requirements-writer agent. Runs through a 3-phase pipeline (scan \u2192 draft \u2192 trace), one phase per session, tracked by req:* GitHub issue labels.",
4448
+ // src/agent/bundles/research-pipeline.ts
4449
+ var researchAnalystSubAgent = {
4450
+ name: "research-analyst",
4451
+ description: "Runs a generic research micro-task pipeline (scope, slice search/synthesize, verify). One phase per session, tracked by research:* GitHub issue labels with filesystem-based durability between phases.",
3432
4452
  model: AGENT_MODEL.POWERFUL,
3433
4453
  maxTurns: 80,
3434
4454
  platforms: { cursor: { exclude: true } },
3435
4455
  prompt: [
3436
- "# Requirements Analyst Agent",
4456
+ "# Research Analyst Agent",
3437
4457
  "",
3438
- "Dedicated agent loop for discovering requirement gaps from BCM (Business",
3439
- "Capability Model) documents, product docs, and competitive analysis \u2014 then",
3440
- "creating well-formed requirement issues for the downstream",
3441
- "requirements-writer (BCM writer) agent to draft. Designed for scheduled",
3442
- "execution downstream of the BCM writer and company research agents.",
4458
+ "Generic research micro-task pipeline. Given a research question, you",
4459
+ "break it into a scope, a fixed number of focused search/synthesize",
4460
+ "slices, and a verification pass that reconciles the slice outputs into",
4461
+ "a single deliverable. Each phase runs as its **own agent session**,",
4462
+ "triggered by a GitHub issue with a `research:*` phase label. You",
4463
+ "handle exactly **one phase per session** \u2014 read the issue to determine",
4464
+ "which phase to execute.",
4465
+ "",
4466
+ "This agent is **domain-neutral**. It makes no assumptions about what",
4467
+ "is being researched (companies, products, people, markets, technical",
4468
+ "topics, academic literature, etc.). All domain-specific vocabulary,",
4469
+ "output locations, and acceptance criteria come from the invoking",
4470
+ "issue body or the consuming project's configuration.",
3443
4471
  "",
3444
4472
  "Follow your project's shared agent conventions (`AGENTS.md`,",
3445
4473
  "`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
3446
4474
  "",
3447
4475
  "---",
3448
4476
  "",
3449
- ...PROJECT_CONTEXT_MAINTAINER_SECTION,
4477
+ ...PROJECT_CONTEXT_READER_SECTION,
3450
4478
  "## Design Principles",
3451
4479
  "",
3452
- "1. **Discover, don't write.** This agent identifies *what requirements are",
3453
- " missing*. The requirements-writer skill writes the actual documents. The",
3454
- " boundary keeps this agent fast and the requirements-writer authoritative.",
3455
- "2. **Trace everything.** Every discovered gap links to the source that",
3456
- " revealed it (a BCM model doc, competitive analysis, product doc, or",
3457
- " meeting extract).",
3458
- "3. **Respect the taxonomy.** Route every discovered requirement to the",
3459
- " correct BCM category (FR, BR, NFR, SEC, DR, INT, OPS, UX, MT, ADR, TR)",
3460
- " using the disambiguation rules in the requirements-writer skill.",
3461
- "4. **Deduplicate.** Before creating an issue, check whether a requirement",
3462
- " already exists or an issue is already open for it.",
4480
+ "1. **Micro-tasks, not mega-prompts.** Split work into small slices so",
4481
+ " each session has a bounded context window and a single deliverable.",
4482
+ "2. **Filesystem durability.** Every phase persists its output to a",
4483
+ " file on disk before closing its issue. Downstream phases read those",
4484
+ " files \u2014 never rely on session memory.",
4485
+ "3. **Issue graph = state machine.** Phase ordering is encoded with",
4486
+ " `Depends on: #N` links between phase issues. A phase runs only",
4487
+ " after its predecessor is closed.",
4488
+ "4. **Generic over specific.** No hardcoded domains, companies, source",
4489
+ " projects, or proprietary taxonomies. Use placeholders that the",
4490
+ " skill invocation or consuming project fills in.",
4491
+ "5. **Verifiable synthesis.** The verify phase re-reads every slice",
4492
+ " output and produces a single deliverable whose claims can each be",
4493
+ " traced back to a slice.",
3463
4494
  "",
3464
4495
  "---",
3465
4496
  "",
3466
4497
  "## State Machine Overview",
3467
4498
  "",
3468
- "Requirements synthesis flows through **3 phases**:",
3469
- "",
3470
4499
  "```",
3471
- "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
3472
- "\u2502 1. SCAN \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 2. DRAFT \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 3. TRACE \u2502",
3473
- "\u2502 Read docs, \u2502 \u2502 Write gap \u2502 \u2502 Create GH \u2502",
3474
- "\u2502 identify \u2502 \u2502 report with \u2502 \u2502 issues and \u2502",
3475
- "\u2502 gaps, check \u2502 \u2502 requirement \u2502 \u2502 update src \u2502",
3476
- "\u2502 for dupes \u2502 \u2502 proposals \u2502 \u2502 docs with \u2502",
3477
- "\u2502 \u2502 \u2502 \u2502 \u2502 traceability\u2502",
3478
- "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
4500
+ "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
4501
+ "\u2502 1. SCOPE \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 2. SLICE (\xD7N) \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 3. VERIFY \u2502",
4502
+ "\u2502 Turn the \u2502 \u2502 For each slice: \u2502 \u2502 Read every \u2502",
4503
+ "\u2502 question \u2502 \u2502 search sources, \u2502 \u2502 slice \u2502",
4504
+ "\u2502 into N \u2502 \u2502 synthesize a \u2502 \u2502 output, \u2502",
4505
+ "\u2502 focused \u2502 \u2502 bounded note file \u2502 \u2502 reconcile, \u2502",
4506
+ "\u2502 slices \u2502 \u2502 \u2502 \u2502 deliverable \u2502",
4507
+ "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
3479
4508
  "```",
3480
4509
  "",
3481
4510
  "**Issue labels encode the phase:**",
3482
4511
  "",
3483
4512
  "| Label | Phase | Session work |",
3484
4513
  "|-------|-------|-------------|",
3485
- "| `req:scan` | 1. Scan | Read source docs, identify potential requirement gaps, check against existing requirements and open issues, write deduplicated scan report |",
3486
- "| `req:draft` | 2. Draft | Write gap report with proposed requirements |",
3487
- "| `req:trace` | 3. Trace | Create GitHub issues for each proposed requirement and update source documents with traceability notes |",
4514
+ "| `research:scope` | 1. Scope | Decompose the research question into N focused slices. Write a scope file. Create N `research:slice` issues. |",
4515
+ "| `research:slice` | 2. Slice | Execute one slice: search authorized sources, synthesize, write a single slice note file. |",
4516
+ "| `research:verify` | 3. Verify | Read every slice note, reconcile findings, produce the final deliverable and a verification report. |",
3488
4517
  "",
3489
- "All issues also carry `type:requirement` and a `status:*` label.",
4518
+ "All issues also carry `type:research` and a `status:*` label.",
3490
4519
  "",
3491
- "**Issue count per scan cycle:** 1 scan + 1 draft + 1 trace = **3 sessions**.",
4520
+ "**Issue count per research cycle:** 1 scope + N slice + 1 verify =",
4521
+ "**N + 2 sessions**. Typical N is 3\u20136.",
3492
4522
  "",
3493
4523
  "**Shortened paths:**",
3494
- "- No gaps found after scan \u2192 skip draft and trace \u2192 **1 session**",
3495
- "- No source docs need traceability updates \u2192 still **3 sessions** (trace",
3496
- " handles both issue creation and doc updates)",
4524
+ "- Scope phase determines the question is unanswerable or out of scope",
4525
+ " \u2192 scope issue closes with a justification and no downstream issues",
4526
+ " are created \u2192 **1 session**.",
4527
+ "- Single-slice research (N = 1) \u2192 **3 sessions**. Never skip verify,",
4528
+ " even with one slice \u2014 verify is where the deliverable lands.",
3497
4529
  "",
3498
4530
  "---",
3499
4531
  "",
3500
4532
  "## Configurable Paths",
3501
4533
  "",
3502
- "Projects adopting this bundle must define these paths in their agent",
3503
- "configuration (`agentConfig.rules` extension or project-level docs):",
4534
+ "The pipeline uses these placeholders. Consuming projects override the",
4535
+ "defaults by passing paths in the `/research` skill invocation or by",
4536
+ "extending this rule in their own `agentConfig.rules`.",
3504
4537
  "",
3505
- "| Placeholder | Meaning | Typical value |",
3506
- "|-------------|---------|---------------|",
3507
- "| `<BCM_DOCS_ROOT>` | Root of BCM model docs (capability models) | `src/content/docs/concepts/` |",
3508
- "| `<COMPETITIVE_ROOT>` | Competitive analysis docs | `src/content/docs/business-strategy/competitive/` |",
3509
- "| `<PRODUCT_ROOT>` | Product roadmap / entity taxonomy | `src/content/docs/product/` |",
3510
- "| `<MEETINGS_ROOT>` | Meeting extracts | `src/content/docs/research/meetings/` |",
3511
- "| `<RESEARCH_REQUIREMENTS_ROOT>` | Scan reports and proposals | `src/content/docs/research/requirements/` |",
3512
- "| `<REQUIREMENTS_ROOT>` | Final requirement documents (owned by requirements-writer) | `src/content/docs/requirements/` |",
3513
- "| `<PREFIX>` | Project-specific requirement ID prefix | e.g. `VRTX`, `ACME` |",
4538
+ "| Placeholder | Meaning | Default |",
4539
+ "|-------------|---------|---------|",
4540
+ "| `<RESEARCH_ROOT>` | Root folder for all research outputs | `docs/research/` |",
4541
+ "| `<SCOPE_DIR>` | Scope files | `<RESEARCH_ROOT>/scopes/` |",
4542
+ "| `<SLICES_DIR>` | Slice note files | `<RESEARCH_ROOT>/slices/` |",
4543
+ "| `<DELIVERABLES_DIR>` | Final verified deliverables | `<RESEARCH_ROOT>/deliverables/` |",
4544
+ "| `<RESEARCH_SLUG>` | Short kebab-case slug identifying one research cycle | derived from the question |",
4545
+ "| `<N>` | Number of slices (default 4, max 8) | `4` |",
3514
4546
  "",
3515
- "If your project stores these in different locations, substitute accordingly",
3516
- "wherever the phase instructions reference a path.",
4547
+ "If `docs/project-context.md` specifies a different research tree,",
4548
+ "prefer that. Otherwise fall back to the defaults above.",
3517
4549
  "",
3518
4550
  "---",
3519
4551
  "",
@@ -3521,348 +4553,340 @@ var requirementsAnalystSubAgent = {
3521
4553
  "",
3522
4554
  "Run this loop exactly once per session. Never start a second issue.",
3523
4555
  "",
3524
- "1. Claim one open `type:requirement` issue using phase priority:",
3525
- " `req:scan` > `req:draft` > `req:trace`.",
3526
- "2. Transition `status:ready` \u2192 `status:in-progress` and create the branch",
3527
- " per your project's branch-naming convention.",
3528
- "3. Execute the phase handler that matches the issue's `req:*` label.",
3529
- "4. Commit, push, open a PR (if applicable), and close the issue per your",
3530
- " project's PR workflow.",
4556
+ "1. Claim one open `type:research` issue using phase priority:",
4557
+ " `research:scope` > `research:slice` > `research:verify`.",
4558
+ "2. Transition `status:ready` \u2192 `status:in-progress` and create the",
4559
+ " branch per your project's branch-naming convention.",
4560
+ "3. Execute the phase handler that matches the issue's `research:*`",
4561
+ " label.",
4562
+ "4. Commit, push, open a PR (if applicable), and close the issue per",
4563
+ " your project's PR workflow.",
3531
4564
  "",
3532
4565
  "---",
3533
4566
  "",
3534
- "## Phase 1: Scan (`req:scan`)",
3535
- "",
3536
- "**Goal:** Read source documents, identify where requirements are missing,",
3537
- "incomplete, or contradictory, then check each potential gap against existing",
3538
- "requirements and open issues to eliminate duplicates. Produces a single",
3539
- "deduplicated scan report.",
3540
- "",
3541
- "**Budget:** Reading source docs + reading requirement registries + searching",
3542
- "issues. Write one deduplicated scan output file.",
3543
- "",
3544
- "### Scan Sources",
4567
+ "## Phase 1: Scope (`research:scope`)",
3545
4568
  "",
3546
- "The issue specifies which source(s) to scan. Common scan scopes:",
4569
+ "**Goal:** Turn a natural-language research question into a bounded",
4570
+ "scope file and `N` focused slice issues.",
3547
4571
  "",
3548
- "| Scope | What to read | What to look for |",
3549
- "|-------|-------------|-----------------|",
3550
- "| **BCM model doc** | One `{PREFIX}-NNN` doc under `<BCM_DOCS_ROOT>` | The doc's project-relevance section (commonly `## <Project> Relevance` or `## Strategic Implications`) \u2014 gaps where capabilities exist but no FR/BR/INT addresses them. Use `docs/project-context.md` to judge what is relevant. |",
3551
- "| **Competitive analysis** | One `comp-*.md` doc under `<COMPETITIVE_ROOT>` | Feature comparison gaps \u2014 competitor features the product lacks requirements for |",
3552
- "| **Product roadmap** | `<PRODUCT_ROOT>/prioritized-feature-roadmap.md` | Roadmap items without corresponding FRs |",
3553
- "| **Entity taxonomy** | `<PRODUCT_ROOT>/entity-taxonomy.md` | Entities without CRUD requirements (FR), data requirements (DR), or security requirements (SEC) |",
3554
- "| **Meeting extract** | `<MEETINGS_ROOT>/meeting-*.extract.md` | Requirements identified but not yet formalized |",
4572
+ "**Budget:** No web searches in this phase. Read the question, the",
4573
+ "project context, and any cited source material already on disk. Write",
4574
+ "one scope file. Create N slice issues.",
3555
4575
  "",
3556
4576
  "### Steps",
3557
4577
  "",
3558
- "1. **Read the source documents** specified in the issue.",
3559
- "",
3560
- "2. **Identify potential gaps.** For each potential missing requirement:",
3561
- " - Classify into the correct BCM category (FR, BR, NFR, SEC, DR, INT,",
3562
- " OPS, UX, MT, ADR, TR)",
3563
- " - Apply the disambiguation rules from the requirements-writer skill",
3564
- " - Note the source that revealed the gap",
3565
- " - Estimate priority based on the source context",
3566
- "",
3567
- "3. **Read the requirements registry.** Scan `_index.md` files in each",
3568
- " `<REQUIREMENTS_ROOT>/<category>/` directory to know what already exists.",
4578
+ "1. **Read the research question** from the issue body. The body should",
4579
+ " include:",
4580
+ " - The question itself",
4581
+ " - Authorized source categories (e.g. public web, vendor docs, a",
4582
+ " cited local file path) \u2014 if absent, default to public web only",
4583
+ " - Output acceptance criteria for the final deliverable",
4584
+ " - Optional: `<N>` override, `<RESEARCH_SLUG>` override, custom",
4585
+ " output paths",
3569
4586
  "",
3570
- "4. **Search for existing issues.** For each potential gap, search open issues:",
3571
- " ```bash",
3572
- ' gh issue list --label "type:requirement" --state open \\',
3573
- " --json number,title --limit 100",
3574
- " ```",
4587
+ "2. **Derive `<RESEARCH_SLUG>`** if not supplied \u2014 a 3\u20135 word kebab-case",
4588
+ " summary of the question. Ensure the slug is not already in use",
4589
+ " under `<SCOPE_DIR>/`.",
3575
4590
  "",
3576
- "5. **Classify each gap:**",
3577
- " - **New** \u2014 no existing requirement or open issue covers this",
3578
- " - **Duplicate** \u2014 an existing requirement already addresses this",
3579
- " - **In progress** \u2014 an open issue already targets this",
3580
- " - **Partial** \u2014 existing requirement partially covers this; note the gap",
4591
+ "3. **Decompose the question into N slices.** Each slice must:",
4592
+ " - Be answerable independently of the others",
4593
+ " - Fit inside a single agent session's context budget",
4594
+ " - Have a clearly scoped set of sources to consult",
4595
+ " - Produce a bounded note file (target: under 1500 words)",
3581
4596
  "",
3582
- "6. **Write the deduplicated scan report** to:",
3583
- " ```",
3584
- " <RESEARCH_REQUIREMENTS_ROOT>/req-scan-<scope>-<YYYY-MM-DD>.md",
3585
- " ```",
4597
+ "4. **Write the scope file** to",
4598
+ " `<SCOPE_DIR>/<RESEARCH_SLUG>.scope.md`:",
3586
4599
  "",
3587
- " Format:",
3588
4600
  " ```markdown",
3589
4601
  " ---",
3590
- ' title: "Requirements Scan: <scope>"',
4602
+ ' title: "Research Scope: <question>"',
4603
+ " slug: <RESEARCH_SLUG>",
3591
4604
  " date: YYYY-MM-DD",
3592
4605
  " parent_issue: <N>",
3593
- " status: complete",
4606
+ " slice_count: <N>",
3594
4607
  " ---",
3595
4608
  "",
3596
- " # Requirements Scan: <scope>",
4609
+ " # Research Scope: <question>",
3597
4610
  "",
3598
- " ## Source Documents Reviewed",
3599
- " - <path> \u2014 <brief description>",
4611
+ " ## Question",
4612
+ " <verbatim question from the issue>",
3600
4613
  "",
3601
- " ## Existing Requirements Checked",
3602
- " - <category>: <count> existing docs, <count> open issues",
4614
+ " ## Authorized Sources",
4615
+ " - <source category or path>",
3603
4616
  "",
3604
- " ## Identified Gaps (New)",
3605
- " ### Gap 1: <Title>",
3606
- " - **Category:** FR / BR / NFR / SEC / DR / INT / OPS / UX / MT / ADR / TR",
3607
- " - **Source:** <path to doc + section that revealed this gap>",
3608
- " - **Priority:** High / Normal / Low",
3609
- " - **Rationale:** <why this requirement is needed>",
3610
- " - **Duplicate check:** No existing requirement or open issue found",
3611
- " - **Proposed scope:** <1-2 sentences on what the requirement should cover>",
4617
+ " ## Acceptance Criteria",
4618
+ " - [ ] <criterion for the final deliverable>",
3612
4619
  "",
3613
- " ## Already Covered",
3614
- " <list of potential gaps that turned out to already have requirements>",
4620
+ " ## Slices",
4621
+ " ### Slice 1: <title>",
4622
+ " - **Focus:** <what this slice answers>",
4623
+ " - **Sources:** <the subset of authorized sources this slice uses>",
4624
+ " - **Output:** <SLICES_DIR>/<RESEARCH_SLUG>-01-<slug>.slice.md",
3615
4625
  "",
3616
- " ## In Progress",
3617
- " <gaps that already have open issues \u2014 include issue numbers>",
4626
+ " ### Slice 2: <title>",
4627
+ " ...",
3618
4628
  "",
3619
- " ## Ambiguous / Needs Human Decision",
3620
- " <gaps where the correct category or scope is unclear>",
4629
+ " ## Out of Scope",
4630
+ " <sub-questions deliberately excluded from this cycle>",
4631
+ "",
4632
+ " ## Deliverable",
4633
+ " <DELIVERABLES_DIR>/<RESEARCH_SLUG>.md",
3621
4634
  " ```",
3622
4635
  "",
3623
- "7. **Create downstream issues based on findings:**",
3624
- " - If any new gaps were identified \u2192 create `req:draft` issue",
3625
- " (blocked on this issue via `Depends on: #N`).",
3626
- " - If **no gaps** were found \u2192 stop (no further phases needed). Comment",
3627
- " on the issue noting that no gaps were identified, and proceed directly",
3628
- " to commit and push. The scan issue will be marked done with no",
3629
- " downstream work needed.",
4636
+ "5. **Create N `research:slice` issues**, one per slice, each with",
4637
+ " `Depends on: #<scope-issue>`. Each slice issue body references the",
4638
+ " scope file and names the exact slice (by number and title).",
3630
4639
  "",
3631
- "8. **Commit and push.**",
4640
+ "6. **Create one `research:verify` issue** that depends on all N slice",
4641
+ " issues. Its body references the scope file and lists every slice",
4642
+ " output path that verify must read.",
4643
+ "",
4644
+ "7. **Commit and push** the scope file. Close the scope issue.",
3632
4645
  "",
3633
4646
  "---",
3634
4647
  "",
3635
- "## Phase 2: Draft (`req:draft`)",
4648
+ "## Phase 2: Slice (`research:slice`)",
3636
4649
  "",
3637
- "**Goal:** Expand each identified gap into a requirement proposal with enough",
3638
- "detail for the requirements-writer to produce a full document.",
4650
+ "**Goal:** Answer one slice by searching the authorized sources and",
4651
+ "writing a single slice note file.",
3639
4652
  "",
3640
- "**Budget:** No web searches. Reading + writing.",
4653
+ "**Budget:** Search budget is one slice \u2014 do not expand scope. Write",
4654
+ "one slice note. Do not create downstream issues.",
3641
4655
  "",
3642
4656
  "### Steps",
3643
4657
  "",
3644
- "1. **Read the scan report** from Phase 1.",
4658
+ "1. **Read the scope file** referenced in the issue body.",
3645
4659
  "",
3646
- "2. **For each gap**, write a detailed proposal:",
4660
+ "2. **Identify your slice** by number and title. Re-read the slice's",
4661
+ " focus, sources, and output path.",
3647
4662
  "",
3648
- " ```markdown",
3649
- " ## Proposed: <PREFIX>-<NNN> \u2014 <Title>",
4663
+ "3. **Search the authorized sources.** Stay within the source list for",
4664
+ " your slice \u2014 do not broaden to the full scope's source list unless",
4665
+ " the slice explicitly permits it.",
3650
4666
  "",
3651
- " **Category:** <FR/BR/NFR/SEC/DR/INT/OPS/UX/MT/ADR/TR>",
3652
- " **Priority:** <High/Normal/Low>",
3653
- " **Source:** <document path and section>",
4667
+ "4. **Synthesize a slice note** and write it to the slice's output",
4668
+ " path (e.g. `<SLICES_DIR>/<RESEARCH_SLUG>-NN-<slug>.slice.md`):",
3654
4669
  "",
3655
- " ### Summary",
3656
- " <2-3 sentences describing what the requirement should capture>",
4670
+ " ```markdown",
4671
+ " ---",
4672
+ ' title: "Slice NN: <title>"',
4673
+ " slug: <RESEARCH_SLUG>",
4674
+ " slice: NN",
4675
+ " date: YYYY-MM-DD",
4676
+ " parent_scope: <SCOPE_DIR>/<RESEARCH_SLUG>.scope.md",
4677
+ " parent_issue: <N>",
4678
+ " ---",
3657
4679
  "",
3658
- " ### Draft Acceptance Criteria",
3659
- " - [ ] <testable criterion 1>",
3660
- " - [ ] <testable criterion 2>",
3661
- " - [ ] <testable criterion 3>",
4680
+ " # Slice NN: <title>",
3662
4681
  "",
3663
- " ### Traceability",
3664
- " - **Implements:** <BR or parent requirement if applicable>",
3665
- " - **Related:** <existing requirements that interact with this one>",
3666
- " - **Source:** <BCM doc, competitive analysis, or meeting that revealed",
3667
- " the gap \u2014 use a markdown link. If the source is a meeting note, the",
3668
- " downstream requirement doc must include the same meeting as a link in",
3669
- " its Traceability `Related:` list.>",
4682
+ " ## Question",
4683
+ " <the slice-level question>",
3670
4684
  "",
3671
- " ### Decision Authority",
3672
- ' <"Direct write" for BR/FR/NFR/SEC/UX, or "Proposed \u2014 needs human',
3673
- ' decision" for ADR/TR, or "Mixed \u2014 defer technology choices" for',
3674
- " DR/MT/INT/OPS>",
4685
+ " ## Key Findings",
4686
+ " - <finding> \u2014 source: <citation>",
3675
4687
  "",
3676
- " ### Notes for Requirements Writer",
3677
- " <any context the writer should know \u2014 related ADRs, existing partial",
3678
- " coverage, relevant competitive features>",
3679
- " ```",
4688
+ " ## Evidence",
4689
+ " <short quotations, paraphrases, or structured data with citations>",
3680
4690
  "",
3681
- "3. **Write the proposals** to:",
3682
- " ```",
3683
- " <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<YYYY-MM-DD>.md",
3684
- " ```",
4691
+ " ## Gaps / Open Questions",
4692
+ " <anything the slice could not answer inside its budget>",
3685
4693
  "",
3686
- "4. **Determine next sequence numbers.** Check each target category",
3687
- " directory under `<REQUIREMENTS_ROOT>/<category>/` to find the next",
3688
- " available `NNN` for each proposed requirement.",
4694
+ " ## Sources",
4695
+ " - <source URL or file path> \u2014 <date accessed>",
4696
+ " ```",
3689
4697
  "",
3690
- "5. **Create the `req:trace` issue** blocked on this draft issue.",
4698
+ "5. **Stay within the word budget** (default 1500 words). If the slice",
4699
+ " cannot fit, add an `## Overflow` section at the end noting what was",
4700
+ " cut and flag it for the verify phase \u2014 do not expand into other",
4701
+ " slices' territory.",
3691
4702
  "",
3692
- "6. **Commit and push.**",
4703
+ "6. **Commit and push** the slice note. Close the slice issue.",
3693
4704
  "",
3694
4705
  "---",
3695
4706
  "",
3696
- "## Phase 3: Trace (`req:trace`)",
4707
+ "## Phase 3: Verify (`research:verify`)",
3697
4708
  "",
3698
- "**Goal:** Create GitHub issues for each proposed requirement and update",
3699
- "source documents with traceability notes indicating that requirement issues",
3700
- "were created.",
4709
+ "**Goal:** Reconcile every slice into a single verified deliverable.",
3701
4710
  "",
3702
- "**Budget:** No web searches. Issue creation + minor edits to source",
3703
- "documents.",
4711
+ "**Budget:** No new web searches. Read the scope, read every slice",
4712
+ "note, reconcile contradictions, write the deliverable and a short",
4713
+ "verification report.",
3704
4714
  "",
3705
4715
  "### Steps",
3706
4716
  "",
3707
- "1. **Read the proposals** from Phase 2.",
4717
+ "1. **Read the scope file** and every slice note listed in the issue",
4718
+ " body. If any slice file is missing, stop and re-open the",
4719
+ " corresponding slice issue with `status:needs-attention`.",
3708
4720
  "",
3709
- "2. **Create requirement issues.** For each proposal:",
4721
+ "2. **Build a claim index.** For every assertion in any slice, note",
4722
+ " which slice(s) support it and which sources back it.",
3710
4723
  "",
3711
- " All `type:requirement` issues default to `priority:medium` (override",
3712
- " only if the proposal's priority was explicitly High or Low).",
4724
+ "3. **Reconcile contradictions.** When slices disagree:",
4725
+ " - Prefer the slice with stronger sources",
4726
+ " - Flag unresolved contradictions in the verification report",
4727
+ " - Do not silently pick a side",
3713
4728
  "",
3714
- " ```bash",
3715
- " gh issue create \\",
3716
- ' --title "docs(<category>): <PREFIX>-<NNN> \u2014 <title>" \\',
3717
- ' --label "type:requirement" --label "status:ready" --label "priority:medium" \\',
3718
- ' --body "## Objective',
3719
- " Write <PREFIX>-<NNN> \u2014 <title>.",
4729
+ "4. **Write the deliverable** to",
4730
+ " `<DELIVERABLES_DIR>/<RESEARCH_SLUG>.md`. The structure is dictated",
4731
+ " by the acceptance criteria in the scope file. Every factual claim",
4732
+ " in the deliverable must cite at least one slice note.",
3720
4733
  "",
3721
- " ## Context",
3722
- " - **Gap identified by:** requirements scan of <source>",
3723
- " - **Proposals file:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md",
4734
+ "5. **Write a verification report** to",
4735
+ " `<DELIVERABLES_DIR>/<RESEARCH_SLUG>.verify.md`:",
3724
4736
  "",
3725
- " ## Inputs",
3726
- " - **Depends on:** (none)",
3727
- " - **Read:** <RESEARCH_REQUIREMENTS_ROOT>/req-proposals-<scope>-<date>.md, <source docs>",
4737
+ " ```markdown",
4738
+ " ---",
4739
+ ' title: "Verification Report: <question>"',
4740
+ " slug: <RESEARCH_SLUG>",
4741
+ " date: YYYY-MM-DD",
4742
+ " parent_issue: <N>",
4743
+ " slices_read: <count>",
4744
+ " ---",
3728
4745
  "",
3729
- " ## Acceptance Criteria",
3730
- " - [ ] Requirement document follows <category> template",
3731
- " - [ ] Traceability links to source BCM/competitive/product doc",
3732
- " - [ ] Registry index updated",
3733
- " - [ ] Decision authority rules followed (direct write vs. proposed)",
4746
+ " # Verification Report: <question>",
3734
4747
  "",
3735
- " ## Scope Size",
3736
- " small",
4748
+ " ## Acceptance Criteria Coverage",
4749
+ " - [x] <criterion> \u2014 covered by slice(s) <NN, NN>",
4750
+ " - [ ] <criterion> \u2014 **not covered**; gap noted in deliverable",
3737
4751
  "",
3738
- " ## Output Path",
3739
- ' <REQUIREMENTS_ROOT>/<category>/<PREFIX>-<NNN>-<slug>.md"',
3740
- " ```",
4752
+ " ## Slice Coverage",
4753
+ " | Slice | Claims | Reused in deliverable | Notes |",
4754
+ " |-------|--------|-----------------------|-------|",
4755
+ " | 01 | <count> | <count> | |",
3741
4756
  "",
3742
- "3. **Update source documents.** In each BCM model doc or competitive",
3743
- " analysis that was scanned, add a note in the project-relevance /",
3744
- " strategic-implications section (whichever heading the source doc uses)",
3745
- " indicating that a requirement issue was created:",
4757
+ " ## Reconciled Contradictions",
4758
+ " - <short summary of each reconciled contradiction and why>",
3746
4759
  "",
3747
- " ```markdown",
3748
- " - Gap addressed: see [<PREFIX>-<NNN>](<relative path to requirement doc>)",
3749
- " (issue #<N>)",
4760
+ " ## Unresolved Contradictions",
4761
+ " - <contradiction the verifier could not resolve>",
4762
+ "",
4763
+ " ## Gaps",
4764
+ " - <question the pipeline could not answer>",
3750
4765
  " ```",
3751
4766
  "",
3752
- "4. **Comment on the scan issue** with a summary of all issues created and",
3753
- " all docs updated.",
4767
+ "6. **Comment on the scope issue** with a summary linking to the",
4768
+ " deliverable and verification report.",
3754
4769
  "",
3755
- "5. **Commit and push.**",
4770
+ "7. **Commit and push.** Close the verify issue.",
3756
4771
  "",
3757
4772
  "---",
3758
4773
  "",
3759
- "## Coordination with Other Agents",
3760
- "",
3761
- "| Direction | Agent | What |",
3762
- "|-----------|-------|------|",
3763
- "| Upstream | BCM Writer | Scans capability-model docs for project-relevance gaps (judged against `docs/project-context.md`) |",
3764
- "| Upstream | Company Research | Scans competitive analysis for feature comparison gaps |",
3765
- "| Upstream | Meeting Analyst | Scans meeting extracts for requirement proposals |",
3766
- "| Downstream | Requirements Writer (BCM Writer) | Creates `type:requirement` issues for the skill to draft |",
3767
- "",
3768
- "**File boundaries:** Writes to `<RESEARCH_REQUIREMENTS_ROOT>/req-*.md` and",
3769
- "minor traceability edits to `<BCM_DOCS_ROOT>` and `<COMPETITIVE_ROOT>`.",
3770
- "Never writes to `<REQUIREMENTS_ROOT>/` \u2014 that is owned by the",
3771
- "requirements-writer agent.",
4774
+ "## Output Boundaries",
3772
4775
  "",
3773
- "---",
4776
+ "This agent writes **only** to:",
3774
4777
  "",
3775
- "## Blocked Issues",
4778
+ "- `<SCOPE_DIR>/` \u2014 scope files (Phase 1)",
4779
+ "- `<SLICES_DIR>/` \u2014 slice notes (Phase 2)",
4780
+ "- `<DELIVERABLES_DIR>/` \u2014 deliverables and verification reports",
4781
+ " (Phase 3)",
3776
4782
  "",
3777
- "Additional block reasons specific to requirements synthesis:",
3778
- "- Source document has unresolved contradictions",
3779
- "- Category classification is ambiguous (needs human disambiguation)",
3780
- "- Dependent BCM documents are still in draft with placeholder content",
4783
+ "The pipeline produces **notes and deliverables only**. It does not",
4784
+ "open downstream `type:requirement`, profile, or comparison issues \u2014",
4785
+ "those are the responsibility of specialized downstream agents (e.g.",
4786
+ "`requirements-analyst`, `meeting-analyst`) that consume the",
4787
+ "deliverables produced here. Keep this boundary clean so the research",
4788
+ "pipeline stays generic.",
3781
4789
  "",
3782
4790
  "---",
3783
4791
  "",
3784
4792
  "## Rules",
3785
4793
  "",
3786
- "- **Discover, don't write requirements.** Create issues for the",
3787
- " requirements-writer \u2014 don't write requirement documents directly.",
3788
- "- **Deduplicate rigorously.** Check both existing docs and open issues",
3789
- " before flagging a gap.",
3790
- "- **Respect decision authority.** Mark ADR/TR proposals as needing human",
3791
- " decision. Don't create direct-write issues for technology choices.",
3792
- "- **Bidirectional traceability.** Every `req-scan-*.md` and",
3793
- " `req-proposals-*.md` must include a `## Produced` section listing the",
3794
- " downstream requirement issues (and eventual requirement documents) it",
3795
- " spawned, as markdown links; each formal requirement document under",
3796
- " `<REQUIREMENTS_ROOT>/` must include a forward link back to the scan or",
3797
- " proposal that produced it."
4794
+ "- **One phase per session.** Never run two phases back-to-back in a",
4795
+ " single session.",
4796
+ "- **Persist before closing.** Every phase must write its output file",
4797
+ " before closing its issue.",
4798
+ "- **Do not expand scope mid-slice.** Overflow goes into the slice's",
4799
+ " overflow section and is flagged for verify \u2014 not into another",
4800
+ " slice's territory.",
4801
+ "- **Cite everything.** Claims without a source citation do not belong",
4802
+ " in a slice note or deliverable.",
4803
+ "- **Produce notes, not downstream work.** Do not create",
4804
+ " `type:requirement`, profile, or comparison issues from this",
4805
+ " pipeline. Emit deliverables under `<DELIVERABLES_DIR>/` and let",
4806
+ " downstream agents decide what to do with them."
3798
4807
  ].join("\n")
3799
4808
  };
3800
- var scanRequirementsSkill = {
3801
- name: "scan-requirements",
3802
- description: "Kick off a requirements-analyst scan across BCM model docs, competitive analysis, product docs, or meeting extracts. Creates a req:scan issue and dispatches Phase 1.",
4809
+ var researchSkill = {
4810
+ name: "research",
4811
+ description: "Kick off a generic research micro-task pipeline. Creates a research:scope issue and dispatches Phase 1 (Scope) in the research-analyst agent.",
3803
4812
  disableModelInvocation: true,
3804
4813
  userInvocable: true,
3805
4814
  context: "fork",
3806
- agent: "requirements-analyst",
4815
+ agent: "research-analyst",
3807
4816
  platforms: { cursor: { exclude: true } },
3808
4817
  instructions: [
3809
- "# Scan Requirements",
4818
+ "# Research",
3810
4819
  "",
3811
- "Kick off a requirements-analyst scan cycle. Creates a `req:scan` issue",
3812
- "targeted at the requested scope and dispatches Phase 1 (Scan) in the",
3813
- "requirements-analyst agent.",
4820
+ "Kick off a generic research micro-task pipeline. Creates a",
4821
+ "`research:scope` issue carrying the research question and dispatches",
4822
+ "Phase 1 (Scope) in the research-analyst agent.",
3814
4823
  "",
3815
4824
  "## Usage",
3816
4825
  "",
3817
- "/scan-requirements <scope>",
4826
+ "/research <question>",
3818
4827
  "",
3819
- "Where `<scope>` is one of:",
3820
- "- `bcm:<PREFIX-NNN>` \u2014 a single BCM model doc",
3821
- "- `competitive:<slug>` \u2014 a single competitive analysis doc",
3822
- "- `product-roadmap` \u2014 the prioritized feature roadmap",
3823
- "- `entity-taxonomy` \u2014 the entity taxonomy doc",
3824
- "- `meeting:<slug>` \u2014 a meeting extract",
3825
- "- `all-bcm` / `all-competitive` \u2014 full sweep (long-running)",
4828
+ "Optional extensions in the question body:",
4829
+ "- `sources: <list>` \u2014 authorized source categories or file paths",
4830
+ "- `slices: <N>` \u2014 override the default slice count (default 4, max 8)",
4831
+ "- `slug: <kebab-case>` \u2014 override the derived research slug",
4832
+ "- `acceptance: <list>` \u2014 explicit acceptance criteria for the",
4833
+ " deliverable",
4834
+ "",
4835
+ "## Default Paths",
4836
+ "",
4837
+ "If the project has no override in `docs/project-context.md` or",
4838
+ "`agentConfig.rules`, outputs land under:",
4839
+ "",
4840
+ "- `docs/research/scopes/<slug>.scope.md`",
4841
+ "- `docs/research/slices/<slug>-NN-<slice-slug>.slice.md`",
4842
+ "- `docs/research/deliverables/<slug>.md`",
4843
+ "- `docs/research/deliverables/<slug>.verify.md`",
3826
4844
  "",
3827
4845
  "## Steps",
3828
4846
  "",
3829
- "1. Create a `req:scan` issue with `type:requirement`, `priority:medium`,",
3830
- " and `status:ready`. Body must list the files to read and the scan scope.",
3831
- "2. Execute Phase 1 (Scan) of the requirements-analyst agent.",
3832
- "3. If gaps are found, a `req:draft` issue is created automatically.",
4847
+ "1. Create a `research:scope` issue with `type:research`,",
4848
+ " `priority:medium`, and `status:ready`. Body must include the",
4849
+ " verbatim question, authorized sources, and any overrides.",
4850
+ "2. Execute Phase 1 (Scope) of the research-analyst agent.",
4851
+ "3. Phase 1 creates `research:slice` issues (one per slice) and a",
4852
+ " single `research:verify` issue. Each downstream issue declares",
4853
+ " its `Depends on:` predecessor.",
3833
4854
  "",
3834
4855
  "## Output",
3835
4856
  "",
3836
- "- A `req-scan-<scope>-<YYYY-MM-DD>.md` file under the project's research",
3837
- " requirements directory.",
3838
- "- A `req:draft` issue if any gaps were identified."
4857
+ "- A scope file under the project's research scope directory",
4858
+ "- One slice note per slice under the slices directory",
4859
+ "- A single deliverable plus verification report under the deliverables",
4860
+ " directory",
4861
+ "- This pipeline produces **notes and deliverables only** \u2014 it does",
4862
+ " not open downstream `type:requirement` or profile issues."
3839
4863
  ].join("\n")
3840
4864
  };
3841
- var requirementsAnalystBundle = {
3842
- name: "requirements-analyst",
3843
- description: "Requirements gap-discovery agent bundle for BCM-driven projects. 3-phase pipeline (scan, draft, trace) with req:* phase labels.",
3844
- appliesWhen: () => true,
4865
+ var researchPipelineBundle = {
4866
+ name: "research-pipeline",
4867
+ description: "Generic research micro-task pipeline: scope, N-way slice search/synthesize, and verify. Opt-in only; domain-neutral; filesystem-durable between phases.",
4868
+ appliesWhen: () => false,
3845
4869
  rules: [
3846
4870
  {
3847
- name: "requirements-analyst-workflow",
3848
- description: "Describes the 3-phase requirements gap-discovery pipeline, the req:* label taxonomy, and the boundary with the downstream requirements-writer agent.",
4871
+ name: "research-pipeline-workflow",
4872
+ description: "Describes the 3-phase generic research pipeline, the research:* label taxonomy, and the boundary against downstream specialized agents.",
3849
4873
  scope: AGENT_RULE_SCOPE.ALWAYS,
3850
4874
  content: [
3851
- "# Requirements Analyst Workflow",
4875
+ "# Research Pipeline Workflow",
3852
4876
  "",
3853
- "Use `/scan-requirements <scope>` to kick off a requirements gap",
3854
- "discovery cycle. The pipeline runs in 3 phases \u2014 scan, draft, trace \u2014",
3855
- "each tracked by its own GitHub issue labeled `req:scan`, `req:draft`,",
3856
- "or `req:trace`. All issues carry `type:requirement`.",
4877
+ "Use `/research <question>` to kick off a generic research",
4878
+ "micro-task pipeline. The pipeline runs in 3 phases \u2014 scope, slice,",
4879
+ "verify \u2014 each tracked by its own GitHub issue labeled",
4880
+ "`research:scope`, `research:slice`, or `research:verify`. All",
4881
+ "issues carry `type:research`.",
3857
4882
  "",
3858
- "The requirements-analyst *discovers gaps and drafts proposals*; it",
3859
- "does **not** write final requirement documents. Writing is the job of",
3860
- "the downstream requirements-writer (BCM writer) agent. Keep that",
3861
- "boundary clean: proposals land under the research requirements",
3862
- "directory, not under the authoritative requirements tree.",
4883
+ "The pipeline produces **notes and deliverables only**. It does",
4884
+ "not open downstream `type:requirement` or profile issues \u2014 those",
4885
+ "belong to specialized downstream agents that consume the",
4886
+ "deliverables.",
3863
4887
  "",
3864
- "See the `requirements-analyst` agent definition for full workflow",
3865
- "details and phase-by-phase instructions."
4888
+ "See the `research-analyst` agent definition for full workflow",
4889
+ "details, default paths, and phase-by-phase instructions."
3866
4890
  ].join("\n"),
3867
4891
  platforms: {
3868
4892
  cursor: { exclude: true }
@@ -3870,55 +4894,94 @@ var requirementsAnalystBundle = {
3870
4894
  tags: ["workflow"]
3871
4895
  }
3872
4896
  ],
3873
- skills: [scanRequirementsSkill],
3874
- subAgents: [requirementsAnalystSubAgent],
4897
+ skills: [researchSkill],
4898
+ subAgents: [researchAnalystSubAgent],
3875
4899
  labels: [
3876
4900
  {
3877
- name: "type:requirement",
3878
- color: "1D76DB",
3879
- description: "Work that produces or discovers a requirement document (FR, BR, NFR, etc.)"
4901
+ name: "type:research",
4902
+ color: "5319E7",
4903
+ description: "Work that produces or consumes a research note, slice, or deliverable"
3880
4904
  },
3881
4905
  {
3882
- name: "req:scan",
4906
+ name: "research:scope",
3883
4907
  color: "C5DEF5",
3884
- description: "Phase 1: scan source docs for requirement gaps and deduplicate"
4908
+ description: "Phase 1: decompose a research question into N focused slice issues"
3885
4909
  },
3886
4910
  {
3887
- name: "req:draft",
4911
+ name: "research:slice",
3888
4912
  color: "BFDADC",
3889
- description: "Phase 2: draft requirement proposals for the requirements-writer"
4913
+ description: "Phase 2: execute one research slice \u2014 search authorized sources and write a slice note"
3890
4914
  },
3891
4915
  {
3892
- name: "req:trace",
4916
+ name: "research:verify",
3893
4917
  color: "D4C5F9",
3894
- description: "Phase 3: create requirement issues and backfill traceability on source docs"
4918
+ description: "Phase 3: reconcile slice notes into a verified deliverable"
3895
4919
  }
3896
4920
  ]
3897
4921
  };
3898
4922
 
3899
- // src/agent/bundles/research-pipeline.ts
3900
- var researchAnalystSubAgent = {
3901
- name: "research-analyst",
3902
- description: "Runs a generic research micro-task pipeline (scope, slice search/synthesize, verify). One phase per session, tracked by research:* GitHub issue labels with filesystem-based durability between phases.",
4923
+ // src/agent/bundles/slack.ts
4924
+ var slackBundle = {
4925
+ name: "slack",
4926
+ description: "Slack MCP message formatting and best practices",
4927
+ appliesWhen: () => false,
4928
+ rules: [
4929
+ {
4930
+ name: "slack-message-formatting",
4931
+ description: "Format Slack messages with explicit links so bullets and labels render correctly",
4932
+ scope: AGENT_RULE_SCOPE.ALWAYS,
4933
+ content: [
4934
+ "# Slack Message Formatting",
4935
+ "",
4936
+ "When composing or sending messages to Slack (e.g., via Slack MCP tools like `slack_send_message`), use formatting that Slack's mrkdwn parser renders correctly.",
4937
+ "",
4938
+ "## Rules",
4939
+ "",
4940
+ "1. **Use Slack's explicit link syntax** for any link in a message:",
4941
+ " - Format: `<https://example.com|display text>`",
4942
+ " - Text outside the angle brackets (bullets, labels) stays separate and won't merge into the link",
4943
+ "",
4944
+ "2. **Do not rely on auto-linkification** when the message has bullets or labels before URLs \u2014 auto-linked URLs can break or merge with surrounding text",
4945
+ "",
4946
+ "3. **Put each list item on its own line** with a newline between items so list structure is clear",
4947
+ "",
4948
+ "4. **Example \u2014 preferred:**",
4949
+ " ```",
4950
+ " Status update:",
4951
+ "",
4952
+ " \u2022 Feature A: <https://github.com/org/repo/pull/1|repo#1>",
4953
+ " \u2022 Feature B: <https://github.com/org/repo/pull/2|repo#2>",
4954
+ " ```",
4955
+ "",
4956
+ "5. **Avoid:** Plain URLs immediately after a bullet/label on the same line (e.g., `\u2022 Feature A: https://github.com/...`) when sending via API, as it can render with bullets inside or between links"
4957
+ ].join("\n"),
4958
+ tags: ["workflow"]
4959
+ }
4960
+ ]
4961
+ };
4962
+
4963
+ // src/agent/bundles/software-profile.ts
4964
+ var softwareProfileAnalystSubAgent = {
4965
+ name: "software-profile-analyst",
4966
+ description: "Researches a software product (competitor, adjacent, incumbent, enabler, infrastructure, or ecosystem-tool) from public sources, produces a structured markdown profile, and contributes rows to a shared feature matrix ranked against configurable segment-importance weights. One product per session, tracked by software:* GitHub issue labels.",
3903
4967
  model: AGENT_MODEL.POWERFUL,
3904
4968
  maxTurns: 80,
3905
4969
  platforms: { cursor: { exclude: true } },
3906
4970
  prompt: [
3907
- "# Research Analyst Agent",
4971
+ "# Software Profile Analyst Agent",
3908
4972
  "",
3909
- "Generic research micro-task pipeline. Given a research question, you",
3910
- "break it into a scope, a fixed number of focused search/synthesize",
3911
- "slices, and a verification pass that reconciles the slice outputs into",
3912
- "a single deliverable. Each phase runs as its **own agent session**,",
3913
- "triggered by a GitHub issue with a `research:*` phase label. You",
3914
- "handle exactly **one phase per session** \u2014 read the issue to determine",
3915
- "which phase to execute.",
4973
+ "You research a single software product from public sources and write",
4974
+ "a structured markdown profile. Each profile cycle runs across a small",
4975
+ "sequence of GitHub issues \u2014 one per phase \u2014 and produces a single",
4976
+ "profile file on disk, a set of feature-matrix rows, and optional",
4977
+ "follow-up research issues for adjacent products.",
3916
4978
  "",
3917
4979
  "This agent is **domain-neutral**. It makes no assumptions about what",
3918
- "is being researched (companies, products, people, markets, technical",
3919
- "topics, academic literature, etc.). All domain-specific vocabulary,",
3920
- "output locations, and acceptance criteria come from the invoking",
3921
- "issue body or the consuming project's configuration.",
4980
+ "the consuming project sells, which industry it serves, or which",
4981
+ "products matter to it. All domain-specific vocabulary, segment",
4982
+ "weights, feature taxonomies, output locations, and profile-template",
4983
+ "overrides come from the invoking issue body or the consuming",
4984
+ "project's configuration.",
3922
4985
  "",
3923
4986
  "Follow your project's shared agent conventions (`AGENTS.md`,",
3924
4987
  "`CLAUDE.md`, or equivalent) for all commit, branch, and PR rules.",
@@ -3928,75 +4991,144 @@ var researchAnalystSubAgent = {
3928
4991
  ...PROJECT_CONTEXT_READER_SECTION,
3929
4992
  "## Design Principles",
3930
4993
  "",
3931
- "1. **Micro-tasks, not mega-prompts.** Split work into small slices so",
3932
- " each session has a bounded context window and a single deliverable.",
3933
- "2. **Filesystem durability.** Every phase persists its output to a",
3934
- " file on disk before closing its issue. Downstream phases read those",
3935
- " files \u2014 never rely on session memory.",
3936
- "3. **Issue graph = state machine.** Phase ordering is encoded with",
3937
- " `Depends on: #N` links between phase issues. A phase runs only",
3938
- " after its predecessor is closed.",
3939
- "4. **Generic over specific.** No hardcoded domains, companies, source",
3940
- " projects, or proprietary taxonomies. Use placeholders that the",
3941
- " skill invocation or consuming project fills in.",
3942
- "5. **Verifiable synthesis.** The verify phase re-reads every slice",
3943
- " output and produces a single deliverable whose claims can each be",
3944
- " traced back to a slice.",
4994
+ "1. **One product per session.** Never profile two products in a",
4995
+ " single session, even if they came up together.",
4996
+ "2. **Public sources only.** Use the product's own site, docs, pricing",
4997
+ " pages, changelogs, public demos, and similar public material. Do",
4998
+ " not attempt to access gated or paywalled content unless the",
4999
+ " invoking issue body explicitly authorizes it.",
5000
+ "3. **Filesystem durability.** The profile file and feature-matrix",
5001
+ " rows are the deliverables. Both are committed to disk before the",
5002
+ " profile issue closes. Downstream phases read from disk \u2014 never",
5003
+ " rely on session memory.",
5004
+ "4. **Generic over specific.** No hardcoded product types, feature",
5005
+ " taxonomies, or segment assumptions. Use the generic software-type",
5006
+ " taxonomy below and let consuming projects override it via their",
5007
+ " `docs/project-context.md` or `agentConfig.rules`.",
5008
+ "5. **Cite everything.** Every non-trivial factual claim in the",
5009
+ " profile must carry a source citation (URL plus access date).",
5010
+ "6. **Follow-up, don't widen scope.** If the session turns up adjacent",
5011
+ " products worth evaluating, emit a follow-up issue rather than",
5012
+ " expanding the profile beyond its scope.",
5013
+ "7. **Segment weights live in project context.** Segment-importance",
5014
+ " weights belong in `docs/project-context.md` (or an override",
5015
+ " passed in the issue body). This agent reads them; it never",
5016
+ " invents them.",
5017
+ "",
5018
+ "---",
5019
+ "",
5020
+ "## Software Type Taxonomy",
5021
+ "",
5022
+ "Pick exactly one type per software profile. The taxonomy is",
5023
+ "deliberately generic \u2014 consuming projects override it via",
5024
+ "`agentConfig.rules` if they need a domain-specific refinement.",
5025
+ "",
5026
+ "| Type | Use for |",
5027
+ "|------|---------|",
5028
+ "| `competitor` | Products that offer a substitutable feature set to the same buyers for the same jobs-to-be-done. |",
5029
+ "| `adjacent` | Products that solve a neighboring problem or serve an overlapping buyer \u2014 not a direct substitute but worth understanding for positioning and integration. |",
5030
+ "| `incumbent` | Established, widely-deployed products that define the status quo in the space. Often older, broader, and harder to displace. |",
5031
+ "| `enabler` | Products the consuming project might build on, integrate with, or resell. Platforms, SDKs, APIs, and similar building blocks. |",
5032
+ "| `infrastructure` | Lower-level infrastructure or runtime components the consuming project depends on (databases, queues, identity, observability, etc.). |",
5033
+ "| `ecosystem-tool` | Developer tooling, plugins, extensions, or companion products that surround an incumbent or competitor without being one themselves. |",
5034
+ "",
5035
+ "If the product plausibly fits two types, prefer the one that reflects",
5036
+ "the **reason the profile was requested**, and note the secondary",
5037
+ "type in the profile body.",
5038
+ "",
5039
+ "---",
5040
+ "",
5041
+ "## Segment-Importance Weights",
5042
+ "",
5043
+ "Feature ranking uses **segment-importance weights** \u2014 a small table",
5044
+ "that assigns a numeric weight to each customer segment the consuming",
5045
+ "project cares about. Higher weight means the segment matters more to",
5046
+ "the project's own strategy; features that serve high-weight segments",
5047
+ "rank higher in the matrix.",
5048
+ "",
5049
+ "**Convention:** segment weights live in `docs/project-context.md`",
5050
+ "under a `## Segment Weights` section. The format is a simple",
5051
+ "markdown table with `segment` and `weight` columns. Weights are",
5052
+ "non-negative numbers; the scale is project-defined (0\u20131, 0\u201310, and",
5053
+ "0\u2013100 are all valid as long as the project is internally",
5054
+ "consistent).",
5055
+ "",
5056
+ "Example `docs/project-context.md` fragment:",
5057
+ "",
5058
+ "```markdown",
5059
+ "## Segment Weights",
5060
+ "",
5061
+ "| segment | weight |",
5062
+ "|---------|--------|",
5063
+ "| enterprise | 3 |",
5064
+ "| mid-market | 2 |",
5065
+ "| smb | 1 |",
5066
+ "| hobbyist | 0.5 |",
5067
+ "```",
5068
+ "",
5069
+ "If `docs/project-context.md` does not define segment weights,",
5070
+ "**do not invent them**. Either:",
5071
+ "",
5072
+ "- Accept an `weights:` override in the invoking issue body, or",
5073
+ "- Produce the feature matrix with a single segment (`default`)",
5074
+ " weighted `1` and flag the missing weights in the profile's",
5075
+ " `## Open Questions` section.",
3945
5076
  "",
3946
5077
  "---",
3947
5078
  "",
3948
5079
  "## State Machine Overview",
3949
5080
  "",
3950
5081
  "```",
3951
- "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
3952
- "\u2502 1. SCOPE \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 2. SLICE (\xD7N) \u2502\u2500\u2500\u2500\u2500\u25B6\u2502 3. VERIFY \u2502",
3953
- "\u2502 Turn the \u2502 \u2502 For each slice: \u2502 \u2502 Read every \u2502",
3954
- "\u2502 question \u2502 \u2502 search sources, \u2502 \u2502 slice \u2502",
3955
- "\u2502 into N \u2502 \u2502 synthesize a \u2502 \u2502 output, \u2502",
3956
- "\u2502 focused \u2502 \u2502 bounded note file \u2502 \u2502 reconcile, \u2502",
3957
- "\u2502 slices \u2502 \u2502 \u2502 \u2502 deliverable \u2502",
3958
- "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
5082
+ "\u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510 \u250C\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510",
5083
+ "\u2502 1. RESEARCH \u2502\u2500\u2500\u25B6\u2502 2. PROFILE \u2502\u2500\u2500\u25B6\u2502 3. MATRIX \u2502\u2500\u2500\u25B6\u2502 4. FOLLOWUP \u2502",
5084
+ "\u2502 Collect \u2502 \u2502 Write the \u2502 \u2502 Extract \u2502 \u2502 Enqueue \u2502",
5085
+ "\u2502 public \u2502 \u2502 structured \u2502 \u2502 feature rows \u2502 \u2502 research for \u2502",
5086
+ "\u2502 sources into \u2502 \u2502 markdown \u2502 \u2502 and score \u2502 \u2502 adjacent \u2502",
5087
+ "\u2502 bounded \u2502 \u2502 profile to \u2502 \u2502 against the \u2502 \u2502 products \u2502",
5088
+ "\u2502 notes file \u2502 \u2502 <PROFILES>/ \u2502 \u2502 weights \u2502 \u2502 surfaced \u2502",
5089
+ "\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518 \u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518",
3959
5090
  "```",
3960
5091
  "",
3961
5092
  "**Issue labels encode the phase:**",
3962
5093
  "",
3963
5094
  "| Label | Phase | Session work |",
3964
5095
  "|-------|-------|-------------|",
3965
- "| `research:scope` | 1. Scope | Decompose the research question into N focused slices. Write a scope file. Create N `research:slice` issues. |",
3966
- "| `research:slice` | 2. Slice | Execute one slice: search authorized sources, synthesize, write a single slice note file. |",
3967
- "| `research:verify` | 3. Verify | Read every slice note, reconcile findings, produce the final deliverable and a verification report. |",
5096
+ "| `software:research` | 1. Research | Gather public sources. Write a bounded research-notes file. Create the profile issue. |",
5097
+ "| `software:profile` | 2. Profile | Read the research notes. Write the structured profile to `<PROFILES_DIR>`. Create the matrix issue. |",
5098
+ "| `software:matrix` | 3. Matrix | Read the profile. Extract feature rows into `<MATRIX_FILE>`. Score against segment weights. Create the follow-up issue if warranted. |",
5099
+ "| `software:followup` | 4. Followup | Read the profile. Enqueue software-research issues for adjacent products surfaced in the profile. |",
3968
5100
  "",
3969
- "All issues also carry `type:research` and a `status:*` label.",
5101
+ "All issues also carry `type:software-profile` and a `status:*` label.",
3970
5102
  "",
3971
- "**Issue count per research cycle:** 1 scope + N slice + 1 verify =",
3972
- "**N + 2 sessions**. Typical N is 3\u20136.",
5103
+ "**Issue count per product cycle:** 1 research + 1 profile + 1 matrix +",
5104
+ "0\u20131 followup = **3\u20134 sessions**. The followup phase is skipped when",
5105
+ "the profile did not surface any adjacent product worth researching.",
3973
5106
  "",
3974
5107
  "**Shortened paths:**",
3975
- "- Scope phase determines the question is unanswerable or out of scope",
3976
- " \u2192 scope issue closes with a justification and no downstream issues",
3977
- " are created \u2192 **1 session**.",
3978
- "- Single-slice research (N = 1) \u2192 **3 sessions**. Never skip verify,",
3979
- " even with one slice \u2014 verify is where the deliverable lands.",
5108
+ "- Research phase determines the product is out of scope (not",
5109
+ " relevant, insufficient public material) \u2192 research issue closes",
5110
+ " with a justification and no downstream issues are created \u2192 **1 session**.",
5111
+ "- Narrow product with no adjacent candidates \u2192 **3 sessions**.",
3980
5112
  "",
3981
5113
  "---",
3982
5114
  "",
3983
5115
  "## Configurable Paths",
3984
5116
  "",
3985
5117
  "The pipeline uses these placeholders. Consuming projects override the",
3986
- "defaults by passing paths in the `/research` skill invocation or by",
3987
- "extending this rule in their own `agentConfig.rules`.",
5118
+ "defaults by passing paths in the `/profile-software` skill invocation",
5119
+ "or by extending this rule in their own `agentConfig.rules`.",
3988
5120
  "",
3989
5121
  "| Placeholder | Meaning | Default |",
3990
5122
  "|-------------|---------|---------|",
3991
- "| `<RESEARCH_ROOT>` | Root folder for all research outputs | `docs/research/` |",
3992
- "| `<SCOPE_DIR>` | Scope files | `<RESEARCH_ROOT>/scopes/` |",
3993
- "| `<SLICES_DIR>` | Slice note files | `<RESEARCH_ROOT>/slices/` |",
3994
- "| `<DELIVERABLES_DIR>` | Final verified deliverables | `<RESEARCH_ROOT>/deliverables/` |",
3995
- "| `<RESEARCH_SLUG>` | Short kebab-case slug identifying one research cycle | derived from the question |",
3996
- "| `<N>` | Number of slices (default 4, max 8) | `4` |",
5123
+ "| `<SOFTWARE_ROOT>` | Root folder for software profiles | `docs/software/` |",
5124
+ "| `<PROFILES_DIR>` | Final software profile files | `<SOFTWARE_ROOT>/profiles/` |",
5125
+ "| `<NOTES_DIR>` | Research-notes files from Phase 1 | `<SOFTWARE_ROOT>/notes/` |",
5126
+ "| `<MATRIX_FILE>` | Shared feature-matrix file | `<SOFTWARE_ROOT>/feature-matrix.md` |",
5127
+ "| `<PRODUCT_SLUG>` | Short kebab-case slug identifying the product | derived from the product name |",
3997
5128
  "",
3998
- "If `docs/project-context.md` specifies a different research tree,",
3999
- "prefer that. Otherwise fall back to the defaults above.",
5129
+ "If `docs/project-context.md` specifies a different software-research",
5130
+ "tree (for example by reusing the research-pipeline deliverables",
5131
+ "folder), prefer that. Otherwise fall back to the defaults above.",
4000
5132
  "",
4001
5133
  "---",
4002
5134
  "",
@@ -4004,221 +5136,275 @@ var researchAnalystSubAgent = {
4004
5136
  "",
4005
5137
  "Run this loop exactly once per session. Never start a second issue.",
4006
5138
  "",
4007
- "1. Claim one open `type:research` issue using phase priority:",
4008
- " `research:scope` > `research:slice` > `research:verify`.",
5139
+ "1. Claim one open `type:software-profile` issue using phase priority:",
5140
+ " `software:research` > `software:profile` > `software:matrix` >",
5141
+ " `software:followup`.",
4009
5142
  "2. Transition `status:ready` \u2192 `status:in-progress` and create the",
4010
5143
  " branch per your project's branch-naming convention.",
4011
- "3. Execute the phase handler that matches the issue's `research:*`",
5144
+ "3. Execute the phase handler that matches the issue's `software:*`",
4012
5145
  " label.",
4013
5146
  "4. Commit, push, open a PR (if applicable), and close the issue per",
4014
5147
  " your project's PR workflow.",
4015
5148
  "",
4016
5149
  "---",
4017
5150
  "",
4018
- "## Phase 1: Scope (`research:scope`)",
5151
+ "## Phase 1: Research (`software:research`)",
4019
5152
  "",
4020
- "**Goal:** Turn a natural-language research question into a bounded",
4021
- "scope file and `N` focused slice issues.",
5153
+ "**Goal:** Gather public sources into a bounded research-notes file.",
4022
5154
  "",
4023
- "**Budget:** No web searches in this phase. Read the question, the",
4024
- "project context, and any cited source material already on disk. Write",
4025
- "one scope file. Create N slice issues.",
5155
+ "**Budget:** Public web search only, unless the issue body authorizes",
5156
+ "additional sources. Write one notes file. Do not write the profile",
5157
+ "or extend the feature matrix in this phase.",
4026
5158
  "",
4027
5159
  "### Steps",
4028
5160
  "",
4029
- "1. **Read the research question** from the issue body. The body should",
4030
- " include:",
4031
- " - The question itself",
4032
- " - Authorized source categories (e.g. public web, vendor docs, a",
4033
- " cited local file path) \u2014 if absent, default to public web only",
4034
- " - Output acceptance criteria for the final deliverable",
4035
- " - Optional: `<N>` override, `<RESEARCH_SLUG>` override, custom",
4036
- " output paths",
5161
+ "1. **Read the issue body.** It should include:",
5162
+ " - The product name and website (if known)",
5163
+ " - The requested software type from the taxonomy above",
5164
+ " - The reason the profile was requested (framing \u2014 what does the",
5165
+ " invoking project want to learn?)",
5166
+ " - Optional: `<PRODUCT_SLUG>` override, custom output paths,",
5167
+ " `weights:` override for segment-importance weights",
4037
5168
  "",
4038
- "2. **Derive `<RESEARCH_SLUG>`** if not supplied \u2014 a 3\u20135 word kebab-case",
4039
- " summary of the question. Ensure the slug is not already in use",
4040
- " under `<SCOPE_DIR>/`.",
5169
+ "2. **Derive `<PRODUCT_SLUG>`** if not supplied \u2014 a 2\u20134 word",
5170
+ " kebab-case summary of the product name. Ensure the slug is not",
5171
+ " already in use under `<PROFILES_DIR>/` or `<NOTES_DIR>/`.",
4041
5172
  "",
4042
- "3. **Decompose the question into N slices.** Each slice must:",
4043
- " - Be answerable independently of the others",
4044
- " - Fit inside a single agent session's context budget",
4045
- " - Have a clearly scoped set of sources to consult",
4046
- " - Produce a bounded note file (target: under 1500 words)",
5173
+ "3. **Gather sources.** Prioritize in this order:",
5174
+ " - The product's own website (home, product, pricing, docs,",
5175
+ " changelog, integrations)",
5176
+ " - Public documentation, developer references, API docs",
5177
+ " - Public changelogs, release notes, roadmap posts",
5178
+ " - Reputable independent reviews and comparison articles",
5179
+ " - Public issue trackers or community forums when the issue body",
5180
+ " authorizes them",
4047
5181
  "",
4048
- "4. **Write the scope file** to",
4049
- " `<SCOPE_DIR>/<RESEARCH_SLUG>.scope.md`:",
5182
+ "4. **Write a research-notes file** to",
5183
+ " `<NOTES_DIR>/<PRODUCT_SLUG>.notes.md`:",
4050
5184
  "",
4051
5185
  " ```markdown",
4052
5186
  " ---",
4053
- ' title: "Research Scope: <question>"',
4054
- " slug: <RESEARCH_SLUG>",
5187
+ ' title: "Research Notes: <product name>"',
5188
+ " slug: <PRODUCT_SLUG>",
5189
+ " software_type: <one of the taxonomy values>",
4055
5190
  " date: YYYY-MM-DD",
4056
5191
  " parent_issue: <N>",
4057
- " slice_count: <N>",
4058
5192
  " ---",
4059
5193
  "",
4060
- " # Research Scope: <question>",
4061
- "",
4062
- " ## Question",
4063
- " <verbatim question from the issue>",
5194
+ " # Research Notes: <product name>",
4064
5195
  "",
4065
- " ## Authorized Sources",
4066
- " - <source category or path>",
5196
+ " ## Framing",
5197
+ " <why this product was requested and what to learn>",
4067
5198
  "",
4068
- " ## Acceptance Criteria",
4069
- " - [ ] <criterion for the final deliverable>",
5199
+ " ## Raw Findings",
5200
+ " - <finding> \u2014 source: <citation>",
4070
5201
  "",
4071
- " ## Slices",
4072
- " ### Slice 1: <title>",
4073
- " - **Focus:** <what this slice answers>",
4074
- " - **Sources:** <the subset of authorized sources this slice uses>",
4075
- " - **Output:** <SLICES_DIR>/<RESEARCH_SLUG>-01-<slug>.slice.md",
5202
+ " ## Candidate Features",
5203
+ " - <feature name>: <one-line description> \u2014 source: <citation>",
4076
5204
  "",
4077
- " ### Slice 2: <title>",
4078
- " ...",
5205
+ " ## Candidate Adjacent Products",
5206
+ " - <product name> \u2014 source: <citation>",
4079
5207
  "",
4080
- " ## Out of Scope",
4081
- " <sub-questions deliberately excluded from this cycle>",
5208
+ " ## Open Questions",
5209
+ " <anything the notes could not answer from public sources>",
4082
5210
  "",
4083
- " ## Deliverable",
4084
- " <DELIVERABLES_DIR>/<RESEARCH_SLUG>.md",
5211
+ " ## Sources",
5212
+ " - <source URL or file path> \u2014 <date accessed>",
4085
5213
  " ```",
4086
5214
  "",
4087
- "5. **Create N `research:slice` issues**, one per slice, each with",
4088
- " `Depends on: #<scope-issue>`. Each slice issue body references the",
4089
- " scope file and names the exact slice (by number and title).",
4090
- "",
4091
- "6. **Create one `research:verify` issue** that depends on all N slice",
4092
- " issues. Its body references the scope file and lists every slice",
4093
- " output path that verify must read.",
5215
+ "5. **Create the `software:profile` issue** with",
5216
+ " `Depends on: #<research-issue>`. Its body references the notes",
5217
+ " file path and the requested software type.",
4094
5218
  "",
4095
- "7. **Commit and push** the scope file. Close the scope issue.",
5219
+ "6. **Commit and push** the notes file. Close the research issue.",
4096
5220
  "",
4097
5221
  "---",
4098
5222
  "",
4099
- "## Phase 2: Slice (`research:slice`)",
5223
+ "## Phase 2: Profile (`software:profile`)",
4100
5224
  "",
4101
- "**Goal:** Answer one slice by searching the authorized sources and",
4102
- "writing a single slice note file.",
5225
+ "**Goal:** Write the structured software profile from the research",
5226
+ "notes.",
4103
5227
  "",
4104
- "**Budget:** Search budget is one slice \u2014 do not expand scope. Write",
4105
- "one slice note. Do not create downstream issues.",
5228
+ "**Budget:** No new web searches unless explicitly needed to fill a",
5229
+ "gap the notes flagged. Write one profile file.",
4106
5230
  "",
4107
5231
  "### Steps",
4108
5232
  "",
4109
- "1. **Read the scope file** referenced in the issue body.",
4110
- "",
4111
- "2. **Identify your slice** by number and title. Re-read the slice's",
4112
- " focus, sources, and output path.",
4113
- "",
4114
- "3. **Search the authorized sources.** Stay within the source list for",
4115
- " your slice \u2014 do not broaden to the full scope's source list unless",
4116
- " the slice explicitly permits it.",
5233
+ "1. **Read the research-notes file** referenced in the issue body.",
4117
5234
  "",
4118
- "4. **Synthesize a slice note** and write it to the slice's output",
4119
- " path (e.g. `<SLICES_DIR>/<RESEARCH_SLUG>-NN-<slug>.slice.md`):",
5235
+ "2. **Check for duplicates.** If `<PROFILES_DIR>/<PRODUCT_SLUG>.md`",
5236
+ " already exists, open it and decide whether to update in place or",
5237
+ " flag a naming collision. Never silently overwrite a non-trivial",
5238
+ " existing profile.",
5239
+ "",
5240
+ "3. **Write the profile** to `<PROFILES_DIR>/<PRODUCT_SLUG>.md` using",
5241
+ " the template below. All sections are required; use",
5242
+ " `_Not available in public sources._` when a section cannot be",
5243
+ " filled from the notes.",
4120
5244
  "",
4121
5245
  " ```markdown",
4122
5246
  " ---",
4123
- ' title: "Slice NN: <title>"',
4124
- " slug: <RESEARCH_SLUG>",
4125
- " slice: NN",
5247
+ ' title: "<product name>"',
5248
+ " slug: <PRODUCT_SLUG>",
5249
+ " software_type: <one of the taxonomy values>",
5250
+ " website: <primary URL>",
4126
5251
  " date: YYYY-MM-DD",
4127
- " parent_scope: <SCOPE_DIR>/<RESEARCH_SLUG>.scope.md",
4128
5252
  " parent_issue: <N>",
5253
+ " notes: <NOTES_DIR>/<PRODUCT_SLUG>.notes.md",
4129
5254
  " ---",
4130
5255
  "",
4131
- " # Slice NN: <title>",
5256
+ " # <product name>",
4132
5257
  "",
4133
- " ## Question",
4134
- " <the slice-level question>",
5258
+ " ## Summary",
5259
+ " <2\u20134 sentence elevator description: what it does, who it's for>",
4135
5260
  "",
4136
- " ## Key Findings",
4137
- " - <finding> \u2014 source: <citation>",
5261
+ " ## Classification",
5262
+ " - **Primary type:** <taxonomy value>",
5263
+ " - **Secondary type (if any):** <taxonomy value or `n/a`>",
5264
+ " - **Relevance to this project:** <1\u20132 sentences tying the product",
5265
+ " back to the framing from the notes>",
4138
5266
  "",
4139
- " ## Evidence",
4140
- " <short quotations, paraphrases, or structured data with citations>",
5267
+ " ## Offering",
5268
+ " - **Jobs-to-be-done:** <bullet list of core use cases>",
5269
+ " - **Target segments:** <who this product is for; reuse segment",
5270
+ " names from the project's segment-weights table when possible>",
5271
+ " - **Pricing model:** <if disclosed>",
5272
+ " - **Deployment model:** <SaaS / self-hosted / hybrid / on-prem>",
4141
5273
  "",
4142
- " ## Gaps / Open Questions",
4143
- " <anything the slice could not answer inside its budget>",
5274
+ " ## Features",
5275
+ " <grouped bullet list of notable features, each cited. These become",
5276
+ " the rows in the feature matrix during Phase 3.>",
5277
+ "",
5278
+ " ## Technology Signals",
5279
+ " <stack hints from docs, integrations, and public engineering",
5280
+ " content \u2014 each bullet cited>",
5281
+ "",
5282
+ " ## Positioning / Differentiation",
5283
+ " <how the product describes itself and how it differs from adjacent",
5284
+ " products \u2014 use its own language, cited, rather than inferred>",
5285
+ "",
5286
+ " ## Risks / Open Questions",
5287
+ " <what the profile could not answer; flag anything the matrix or",
5288
+ " follow-up phase should escalate>",
5289
+ "",
5290
+ " ## Follow-up Candidates",
5291
+ " - **Adjacent products to evaluate:** <list of candidate product",
5292
+ " names>",
4144
5293
  "",
4145
5294
  " ## Sources",
4146
- " - <source URL or file path> \u2014 <date accessed>",
5295
+ " - <source URL> \u2014 <date accessed>",
4147
5296
  " ```",
4148
5297
  "",
4149
- "5. **Stay within the word budget** (default 1500 words). If the slice",
4150
- " cannot fit, add an `## Overflow` section at the end noting what was",
4151
- " cut and flag it for the verify phase \u2014 do not expand into other",
4152
- " slices' territory.",
5298
+ "4. **Create the `software:matrix` issue** with",
5299
+ " `Depends on: #<profile-issue>`. Its body references the profile",
5300
+ " path, the matrix file path, and the segment-weights source",
5301
+ " (`docs/project-context.md` or an explicit override).",
4153
5302
  "",
4154
- "6. **Commit and push** the slice note. Close the slice issue.",
5303
+ "5. **Commit and push** the profile file. Close the profile issue.",
4155
5304
  "",
4156
5305
  "---",
4157
5306
  "",
4158
- "## Phase 3: Verify (`research:verify`)",
5307
+ "## Phase 3: Matrix (`software:matrix`)",
4159
5308
  "",
4160
- "**Goal:** Reconcile every slice into a single verified deliverable.",
5309
+ "**Goal:** Extract feature rows from the profile into the shared",
5310
+ "feature matrix and score each feature against the segment-importance",
5311
+ "weights.",
4161
5312
  "",
4162
- "**Budget:** No new web searches. Read the scope, read every slice",
4163
- "note, reconcile contradictions, write the deliverable and a short",
4164
- "verification report.",
5313
+ "**Budget:** No new research. Read the profile, update the matrix,",
5314
+ "close the phase.",
5315
+ "",
5316
+ "### Matrix File Format",
5317
+ "",
5318
+ "The feature matrix is a single markdown file at `<MATRIX_FILE>`. It",
5319
+ "uses a wide table with one row per (product, feature) pair and one",
5320
+ "column per segment plus a computed `score` column.",
5321
+ "",
5322
+ "```markdown",
5323
+ "---",
5324
+ 'title: "Software Feature Matrix"',
5325
+ "weights_source: docs/project-context.md#segment-weights",
5326
+ "updated: YYYY-MM-DD",
5327
+ "---",
5328
+ "",
5329
+ "# Software Feature Matrix",
5330
+ "",
5331
+ "| product | feature | <segment-1> | <segment-2> | ... | score | source |",
5332
+ "|---------|---------|-------------|-------------|-----|-------|--------|",
5333
+ "| <slug> | <feature-name> | 0\u20131 | 0\u20131 | ... | <weighted-sum> | <profile-path> |",
5334
+ "```",
5335
+ "",
5336
+ "Segment columns carry a **coverage score** in `[0, 1]` representing",
5337
+ "how well the feature serves that segment \u2014 `1` means fully covered,",
5338
+ "`0` means not covered, intermediate values reflect partial coverage",
5339
+ "(e.g. self-serve only, gated by pricing tier, limited by scale).",
5340
+ "",
5341
+ "The `score` column is the weighted sum:",
5342
+ "",
5343
+ "```",
5344
+ "score = \u03A3 (coverage[segment] * weight[segment])",
5345
+ "```",
5346
+ "",
5347
+ "using the weights loaded from `docs/project-context.md`.",
4165
5348
  "",
4166
5349
  "### Steps",
4167
5350
  "",
4168
- "1. **Read the scope file** and every slice note listed in the issue",
4169
- " body. If any slice file is missing, stop and re-open the",
4170
- " corresponding slice issue with `status:needs-attention`.",
5351
+ "1. **Load segment weights.** Read `## Segment Weights` from",
5352
+ " `docs/project-context.md`. If absent, fall back to the",
5353
+ " `weights:` override in the issue body, or the single-segment",
5354
+ " default described in `## Segment-Importance Weights` above.",
4171
5355
  "",
4172
- "2. **Build a claim index.** For every assertion in any slice, note",
4173
- " which slice(s) support it and which sources back it.",
5356
+ "2. **Read the profile file** referenced in the issue body. Extract",
5357
+ " the bullets under `## Features` as candidate matrix rows.",
4174
5358
  "",
4175
- "3. **Reconcile contradictions.** When slices disagree:",
4176
- " - Prefer the slice with stronger sources",
4177
- " - Flag unresolved contradictions in the verification report",
4178
- " - Do not silently pick a side",
5359
+ "3. **Open or create `<MATRIX_FILE>`.** If the file does not exist,",
5360
+ " write the front-matter and header row using the current set of",
5361
+ " segment columns. If it exists, ensure its segment columns match",
5362
+ " the loaded weights; if they have drifted, add any missing columns",
5363
+ " and leave a note in the profile's `## Risks / Open Questions`.",
4179
5364
  "",
4180
- "4. **Write the deliverable** to",
4181
- " `<DELIVERABLES_DIR>/<RESEARCH_SLUG>.md`. The structure is dictated",
4182
- " by the acceptance criteria in the scope file. Every factual claim",
4183
- " in the deliverable must cite at least one slice note.",
5365
+ "4. **Append or update rows** for the current product. One row per",
5366
+ " feature. For each row:",
5367
+ " - Assign a coverage score in `[0, 1]` for each segment, citing",
5368
+ " the profile section that justifies the score.",
5369
+ " - Compute the `score` as the weighted sum.",
5370
+ " - Set the `source` column to the profile file path.",
4184
5371
  "",
4185
- "5. **Write a verification report** to",
4186
- " `<DELIVERABLES_DIR>/<RESEARCH_SLUG>.verify.md`:",
5372
+ "5. **Update the matrix front-matter** (`updated: YYYY-MM-DD`).",
4187
5373
  "",
4188
- " ```markdown",
4189
- " ---",
4190
- ' title: "Verification Report: <question>"',
4191
- " slug: <RESEARCH_SLUG>",
4192
- " date: YYYY-MM-DD",
4193
- " parent_issue: <N>",
4194
- " slices_read: <count>",
4195
- " ---",
5374
+ "6. **Decide whether a follow-up issue is warranted.** Create a",
5375
+ " `software:followup` issue (depending on this matrix issue) only",
5376
+ " if the profile lists at least one adjacent product candidate.",
5377
+ " Otherwise, note in the matrix issue's closing comment that no",
5378
+ " follow-up is needed.",
4196
5379
  "",
4197
- " # Verification Report: <question>",
5380
+ "7. **Commit and push** the matrix file (and any profile updates).",
5381
+ " Close the matrix issue.",
4198
5382
  "",
4199
- " ## Acceptance Criteria Coverage",
4200
- " - [x] <criterion> \u2014 covered by slice(s) <NN, NN>",
4201
- " - [ ] <criterion> \u2014 **not covered**; gap noted in deliverable",
5383
+ "---",
4202
5384
  "",
4203
- " ## Slice Coverage",
4204
- " | Slice | Claims | Reused in deliverable | Notes |",
4205
- " |-------|--------|-----------------------|-------|",
4206
- " | 01 | <count> | <count> | |",
5385
+ "## Phase 4: Followup (`software:followup`)",
4207
5386
  "",
4208
- " ## Reconciled Contradictions",
4209
- " - <short summary of each reconciled contradiction and why>",
5387
+ "**Goal:** Create downstream research issues for the adjacent products",
5388
+ "surfaced in the profile.",
4210
5389
  "",
4211
- " ## Unresolved Contradictions",
4212
- " - <contradiction the verifier could not resolve>",
5390
+ "**Budget:** No new research. Read the profile, enqueue issues, close",
5391
+ "the phase.",
4213
5392
  "",
4214
- " ## Gaps",
4215
- " - <question the pipeline could not answer>",
4216
- " ```",
5393
+ "### Steps",
4217
5394
  "",
4218
- "6. **Comment on the scope issue** with a summary linking to the",
4219
- " deliverable and verification report.",
5395
+ "1. **Read the profile file** referenced in the issue body.",
4220
5396
  "",
4221
- "7. **Commit and push.** Close the verify issue.",
5397
+ "2. **Enqueue software-research issues** for each entry under",
5398
+ " `Follow-up Candidates > Adjacent products to evaluate`. Each new",
5399
+ " issue follows the same 4-phase pipeline \u2014 start it in the",
5400
+ " `software:research` phase with `type:software-profile`,",
5401
+ " `priority:medium`, and `status:ready`.",
5402
+ "",
5403
+ "3. **Cross-link** \u2014 update the profile's `## Follow-up Candidates`",
5404
+ " section so each entry references its newly-created issue number.",
5405
+ "",
5406
+ "4. **Commit and push** (if the profile was updated). Close the",
5407
+ " followup issue.",
4222
5408
  "",
4223
5409
  "---",
4224
5410
  "",
@@ -4226,118 +5412,133 @@ var researchAnalystSubAgent = {
4226
5412
  "",
4227
5413
  "This agent writes **only** to:",
4228
5414
  "",
4229
- "- `<SCOPE_DIR>/` \u2014 scope files (Phase 1)",
4230
- "- `<SLICES_DIR>/` \u2014 slice notes (Phase 2)",
4231
- "- `<DELIVERABLES_DIR>/` \u2014 deliverables and verification reports",
4232
- " (Phase 3)",
5415
+ "- `<NOTES_DIR>/` \u2014 research-notes files (Phase 1)",
5416
+ "- `<PROFILES_DIR>/` \u2014 software profiles (Phase 2, updated in later",
5417
+ " phases)",
5418
+ "- `<MATRIX_FILE>` \u2014 shared feature matrix (Phase 3)",
4233
5419
  "",
4234
- "The pipeline produces **notes and deliverables only**. It does not",
4235
- "open downstream `type:requirement`, profile, or comparison issues \u2014",
4236
- "those are the responsibility of specialized downstream agents (e.g.",
4237
- "`requirements-analyst`, `meeting-analyst`) that consume the",
4238
- "deliverables produced here. Keep this boundary clean so the research",
4239
- "pipeline stays generic.",
5420
+ "The pipeline produces **profiles, notes, and matrix rows only**.",
5421
+ "Deeper research on adjacent products is delegated to new cycles of",
5422
+ "this same pipeline via follow-up issues. This agent never writes",
5423
+ "company profiles, person profiles, formal requirement documents, or",
5424
+ "comparative long-form analyses itself. Keep this boundary clean so",
5425
+ "the software-profile pipeline stays generic.",
4240
5426
  "",
4241
5427
  "---",
4242
5428
  "",
4243
5429
  "## Rules",
4244
5430
  "",
4245
- "- **One phase per session.** Never run two phases back-to-back in a",
4246
- " single session.",
5431
+ "- **One product per session.** Never profile two products back-to-back.",
4247
5432
  "- **Persist before closing.** Every phase must write its output file",
4248
5433
  " before closing its issue.",
4249
- "- **Do not expand scope mid-slice.** Overflow goes into the slice's",
4250
- " overflow section and is flagged for verify \u2014 not into another",
4251
- " slice's territory.",
4252
- "- **Cite everything.** Claims without a source citation do not belong",
4253
- " in a slice note or deliverable.",
4254
- "- **Produce notes, not downstream work.** Do not create",
4255
- " `type:requirement`, profile, or comparison issues from this",
4256
- " pipeline. Emit deliverables under `<DELIVERABLES_DIR>/` and let",
4257
- " downstream agents decide what to do with them."
5434
+ "- **Cite everything.** Profile claims without source citations do not",
5435
+ " belong in the deliverable.",
5436
+ "- **No invented weights.** Segment weights come from",
5437
+ " `docs/project-context.md` or an explicit issue-body override. If",
5438
+ " neither is available, fall back to the single-segment default and",
5439
+ " flag the gap \u2014 never guess.",
5440
+ "- **Produce profiles and matrix rows, not downstream work.** Do not",
5441
+ " open `type:requirement` or formal evaluation issues from this",
5442
+ " pipeline. Follow-up work is scoped through `software:followup` or",
5443
+ " delegated to downstream research agents."
4258
5444
  ].join("\n")
4259
5445
  };
4260
- var researchSkill = {
4261
- name: "research",
4262
- description: "Kick off a generic research micro-task pipeline. Creates a research:scope issue and dispatches Phase 1 (Scope) in the research-analyst agent.",
5446
+ var profileSoftwareSkill = {
5447
+ name: "profile-software",
5448
+ description: "Kick off a software-profile pipeline. Creates a software:research issue for the given product and dispatches Phase 1 (Research) in the software-profile-analyst agent.",
4263
5449
  disableModelInvocation: true,
4264
5450
  userInvocable: true,
4265
5451
  context: "fork",
4266
- agent: "research-analyst",
5452
+ agent: "software-profile-analyst",
4267
5453
  platforms: { cursor: { exclude: true } },
4268
5454
  instructions: [
4269
- "# Research",
5455
+ "# Profile Software",
4270
5456
  "",
4271
- "Kick off a generic research micro-task pipeline. Creates a",
4272
- "`research:scope` issue carrying the research question and dispatches",
4273
- "Phase 1 (Scope) in the research-analyst agent.",
5457
+ "Kick off a software-profile pipeline. Creates a `software:research`",
5458
+ "issue carrying the product name, type, and framing, then dispatches",
5459
+ "Phase 1 (Research) in the software-profile-analyst agent.",
4274
5460
  "",
4275
5461
  "## Usage",
4276
5462
  "",
4277
- "/research <question>",
5463
+ "/profile-software <product-name>",
4278
5464
  "",
4279
- "Optional extensions in the question body:",
4280
- "- `sources: <list>` \u2014 authorized source categories or file paths",
4281
- "- `slices: <N>` \u2014 override the default slice count (default 4, max 8)",
4282
- "- `slug: <kebab-case>` \u2014 override the derived research slug",
4283
- "- `acceptance: <list>` \u2014 explicit acceptance criteria for the",
4284
- " deliverable",
5465
+ "Optional extensions in the issue body:",
5466
+ "- `type: <competitor | adjacent | incumbent | enabler |",
5467
+ " infrastructure | ecosystem-tool>` \u2014 override the default type",
5468
+ " inference",
5469
+ "- `website: <url>` \u2014 canonical website if not obvious from the name",
5470
+ "- `framing: <text>` \u2014 why this profile was requested and what to learn",
5471
+ "- `slug: <kebab-case>` \u2014 override the derived product slug",
5472
+ "- `weights: <table>` \u2014 override the segment-importance weights for",
5473
+ " this profile cycle (otherwise loaded from",
5474
+ " `docs/project-context.md`)",
5475
+ "- `sources: <list>` \u2014 additional authorized sources beyond public web",
4285
5476
  "",
4286
5477
  "## Default Paths",
4287
5478
  "",
4288
5479
  "If the project has no override in `docs/project-context.md` or",
4289
5480
  "`agentConfig.rules`, outputs land under:",
4290
5481
  "",
4291
- "- `docs/research/scopes/<slug>.scope.md`",
4292
- "- `docs/research/slices/<slug>-NN-<slice-slug>.slice.md`",
4293
- "- `docs/research/deliverables/<slug>.md`",
4294
- "- `docs/research/deliverables/<slug>.verify.md`",
5482
+ "- `docs/software/notes/<slug>.notes.md`",
5483
+ "- `docs/software/profiles/<slug>.md`",
5484
+ "- `docs/software/feature-matrix.md` (shared across all products)",
4295
5485
  "",
4296
5486
  "## Steps",
4297
5487
  "",
4298
- "1. Create a `research:scope` issue with `type:research`,",
5488
+ "1. Create a `software:research` issue with `type:software-profile`,",
4299
5489
  " `priority:medium`, and `status:ready`. Body must include the",
4300
- " verbatim question, authorized sources, and any overrides.",
4301
- "2. Execute Phase 1 (Scope) of the research-analyst agent.",
4302
- "3. Phase 1 creates `research:slice` issues (one per slice) and a",
4303
- " single `research:verify` issue. Each downstream issue declares",
4304
- " its `Depends on:` predecessor.",
5490
+ " product name, selected type, framing, and any overrides.",
5491
+ "2. Execute Phase 1 (Research) of the software-profile-analyst",
5492
+ " agent.",
5493
+ "3. Phase 1 creates the `software:profile` issue. Phase 2 creates",
5494
+ " the `software:matrix` issue. Phase 3 may create a",
5495
+ " `software:followup` issue. Each downstream issue declares its",
5496
+ " `Depends on:` predecessor.",
4305
5497
  "",
4306
5498
  "## Output",
4307
5499
  "",
4308
- "- A scope file under the project's research scope directory",
4309
- "- One slice note per slice under the slices directory",
4310
- "- A single deliverable plus verification report under the deliverables",
4311
- " directory",
4312
- "- This pipeline produces **notes and deliverables only** \u2014 it does",
4313
- " not open downstream `type:requirement` or profile issues."
5500
+ "- A research-notes file under the project's notes directory",
5501
+ "- A single software profile under the profiles directory",
5502
+ "- One or more rows appended to the shared feature-matrix file,",
5503
+ " scored against the configured segment weights",
5504
+ "- Optional follow-up research issues for adjacent products",
5505
+ " surfaced in the profile",
5506
+ "- This pipeline produces **profiles, notes, and matrix rows only**",
5507
+ " \u2014 it does not write company profiles, person profiles, or formal",
5508
+ " requirement documents itself."
4314
5509
  ].join("\n")
4315
5510
  };
4316
- var researchPipelineBundle = {
4317
- name: "research-pipeline",
4318
- description: "Generic research micro-task pipeline: scope, N-way slice search/synthesize, and verify. Opt-in only; domain-neutral; filesystem-durable between phases.",
5511
+ var softwareProfileBundle = {
5512
+ name: "software-profile",
5513
+ description: "Software research, profiling, and feature-matrix pipeline: research, profile, matrix, followup. Opt-in only; domain-neutral; filesystem-durable between phases; ranks features against configurable segment-importance weights.",
4319
5514
  appliesWhen: () => false,
4320
5515
  rules: [
4321
5516
  {
4322
- name: "research-pipeline-workflow",
4323
- description: "Describes the 3-phase generic research pipeline, the research:* label taxonomy, and the boundary against downstream specialized agents.",
5517
+ name: "software-profile-workflow",
5518
+ description: "Describes the 4-phase software-profile pipeline, the software:* label taxonomy, the generic software-type taxonomy, and the segment-weights convention that drives feature-matrix scoring.",
4324
5519
  scope: AGENT_RULE_SCOPE.ALWAYS,
4325
5520
  content: [
4326
- "# Research Pipeline Workflow",
4327
- "",
4328
- "Use `/research <question>` to kick off a generic research",
4329
- "micro-task pipeline. The pipeline runs in 3 phases \u2014 scope, slice,",
4330
- "verify \u2014 each tracked by its own GitHub issue labeled",
4331
- "`research:scope`, `research:slice`, or `research:verify`. All",
4332
- "issues carry `type:research`.",
4333
- "",
4334
- "The pipeline produces **notes and deliverables only**. It does",
4335
- "not open downstream `type:requirement` or profile issues \u2014 those",
4336
- "belong to specialized downstream agents that consume the",
4337
- "deliverables.",
4338
- "",
4339
- "See the `research-analyst` agent definition for full workflow",
4340
- "details, default paths, and phase-by-phase instructions."
5521
+ "# Software Profile Workflow",
5522
+ "",
5523
+ "Use `/profile-software <product-name>` to kick off a software",
5524
+ "research, profiling, and feature-matrix pipeline. The pipeline",
5525
+ "runs in up to 4 phases \u2014 research, profile, matrix, followup \u2014",
5526
+ "each tracked by its own GitHub issue labeled",
5527
+ "`software:research`, `software:profile`, `software:matrix`, or",
5528
+ "`software:followup`. All issues carry `type:software-profile`.",
5529
+ "",
5530
+ "The pipeline produces **software profiles, research notes, and",
5531
+ "rows in a shared feature matrix**. Features are ranked against",
5532
+ "segment-importance weights declared in",
5533
+ "`docs/project-context.md` under a `## Segment Weights` section.",
5534
+ "Deeper research on adjacent products surfaced in a profile is",
5535
+ "delegated to new cycles of this same pipeline via",
5536
+ "`software:followup` issues.",
5537
+ "",
5538
+ "See the `software-profile-analyst` agent definition for full",
5539
+ "workflow details, default paths, the software-type taxonomy,",
5540
+ "the segment-weights convention, and phase-by-phase",
5541
+ "instructions."
4341
5542
  ].join("\n"),
4342
5543
  platforms: {
4343
5544
  cursor: { exclude: true }
@@ -4345,68 +5546,33 @@ var researchPipelineBundle = {
4345
5546
  tags: ["workflow"]
4346
5547
  }
4347
5548
  ],
4348
- skills: [researchSkill],
4349
- subAgents: [researchAnalystSubAgent],
5549
+ skills: [profileSoftwareSkill],
5550
+ subAgents: [softwareProfileAnalystSubAgent],
4350
5551
  labels: [
4351
5552
  {
4352
- name: "type:research",
4353
- color: "5319E7",
4354
- description: "Work that produces or consumes a research note, slice, or deliverable"
5553
+ name: "type:software-profile",
5554
+ color: "0E8A16",
5555
+ description: "Work that produces or maintains a software profile, research notes, or feature-matrix rows"
4355
5556
  },
4356
5557
  {
4357
- name: "research:scope",
5558
+ name: "software:research",
4358
5559
  color: "C5DEF5",
4359
- description: "Phase 1: decompose a research question into N focused slice issues"
5560
+ description: "Phase 1: gather public sources about a software product into a research-notes file"
4360
5561
  },
4361
5562
  {
4362
- name: "research:slice",
5563
+ name: "software:profile",
4363
5564
  color: "BFDADC",
4364
- description: "Phase 2: execute one research slice \u2014 search authorized sources and write a slice note"
5565
+ description: "Phase 2: write the structured software profile from research notes"
4365
5566
  },
4366
5567
  {
4367
- name: "research:verify",
5568
+ name: "software:matrix",
4368
5569
  color: "D4C5F9",
4369
- description: "Phase 3: reconcile slice notes into a verified deliverable"
4370
- }
4371
- ]
4372
- };
4373
-
4374
- // src/agent/bundles/slack.ts
4375
- var slackBundle = {
4376
- name: "slack",
4377
- description: "Slack MCP message formatting and best practices",
4378
- appliesWhen: () => false,
4379
- rules: [
5570
+ description: "Phase 3: extract feature rows into the shared feature matrix and score them against segment weights"
5571
+ },
4380
5572
  {
4381
- name: "slack-message-formatting",
4382
- description: "Format Slack messages with explicit links so bullets and labels render correctly",
4383
- scope: AGENT_RULE_SCOPE.ALWAYS,
4384
- content: [
4385
- "# Slack Message Formatting",
4386
- "",
4387
- "When composing or sending messages to Slack (e.g., via Slack MCP tools like `slack_send_message`), use formatting that Slack's mrkdwn parser renders correctly.",
4388
- "",
4389
- "## Rules",
4390
- "",
4391
- "1. **Use Slack's explicit link syntax** for any link in a message:",
4392
- " - Format: `<https://example.com|display text>`",
4393
- " - Text outside the angle brackets (bullets, labels) stays separate and won't merge into the link",
4394
- "",
4395
- "2. **Do not rely on auto-linkification** when the message has bullets or labels before URLs \u2014 auto-linked URLs can break or merge with surrounding text",
4396
- "",
4397
- "3. **Put each list item on its own line** with a newline between items so list structure is clear",
4398
- "",
4399
- "4. **Example \u2014 preferred:**",
4400
- " ```",
4401
- " Status update:",
4402
- "",
4403
- " \u2022 Feature A: <https://github.com/org/repo/pull/1|repo#1>",
4404
- " \u2022 Feature B: <https://github.com/org/repo/pull/2|repo#2>",
4405
- " ```",
4406
- "",
4407
- "5. **Avoid:** Plain URLs immediately after a bullet/label on the same line (e.g., `\u2022 Feature A: https://github.com/...`) when sending via API, as it can render with bullets inside or between links"
4408
- ].join("\n"),
4409
- tags: ["workflow"]
5573
+ name: "software:followup",
5574
+ color: "FBCA04",
5575
+ description: "Phase 4: enqueue follow-up research issues for adjacent products surfaced in the profile"
4410
5576
  }
4411
5577
  ]
4412
5578
  };
@@ -5023,7 +6189,9 @@ var BUILT_IN_BUNDLES = [
5023
6189
  prReviewBundle,
5024
6190
  requirementsAnalystBundle,
5025
6191
  researchPipelineBundle,
5026
- companyProfileBundle
6192
+ companyProfileBundle,
6193
+ peopleProfileBundle,
6194
+ softwareProfileBundle
5027
6195
  ];
5028
6196
 
5029
6197
  // src/agent/bundles/scope.ts
@@ -8561,6 +9729,7 @@ export {
8561
9729
  jestBundle,
8562
9730
  meetingAnalysisBundle,
8563
9731
  orchestratorBundle,
9732
+ peopleProfileBundle,
8564
9733
  pnpmBundle,
8565
9734
  prReviewBundle,
8566
9735
  projenBundle,
@@ -8569,6 +9738,7 @@ export {
8569
9738
  resolveModelAlias,
8570
9739
  resolveTemplateVariables,
8571
9740
  slackBundle,
9741
+ softwareProfileBundle,
8572
9742
  turborepoBundle,
8573
9743
  typescriptBundle,
8574
9744
  vitestBundle