feat: add GitHub workflows to sync agents/ to Devin Knowledge

[eunjae-lee]

What does this PR do?

Adds automation to sync the agents/ folder documentation to Devin's Knowledge API. This enables automatic updates to Devin's knowledge base whenever agent documentation is modified.

Components added:

• scripts/devin/parse-local-knowledge.ts - Converts agents/ markdown files to Devin Knowledge JSON format
• scripts/devin/validate-local-knowledge.ts - Validates rules have proper frontmatter (title, tags) and knowledge-base sections start with "When..."
• scripts/devin/sync-knowledge-to-devin.ts - Syncs knowledge entries to Devin API (create/update)
• scripts/devin/export-devin-knowledge.ts - Backup script to export existing Devin knowledge
• Two GitHub workflows:
  • validate-agents-format.yml - Runs on PRs modifying agents/**
  • sync-agents-to-devin.yml - Runs on merge to main for agents/** changes

Mandatory Tasks (DO NOT REMOVE)

• I have self-reviewed the code (A decent size PR without self-review might be rejected).
• I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. N/A - internal tooling only.
• I confirm automated tests are in place that prove my fix is effective or that my feature works.

How should this be tested?

1. Validation script: Run npx tsx scripts/devin/validate-local-knowledge.ts - should pass with "All files are valid!"
2. Parser script: Run npx tsx scripts/devin/parse-local-knowledge.ts - generates agents/devin-knowledge.json with ~55 entries
3. Sync script: Requires DEVIN_API_TOKEN env var - not tested against live API yet

Before merging:

• Add DEVIN_API_TOKEN as a GitHub secret for the sync workflow to work
• Verify the folder creation API endpoint (/knowledge/folders) is correct - I assumed this path based on the docs

Checklist

• My code follows the style guidelines of this project
• I have commented my code, particularly in hard-to-understand areas
• I have checked if my changes generate no new warnings

---

Human review focus areas:

• The scripts use path.join(__dirname, "..", "..", "agents") to reference the agents folder - verify this path logic works in CI
• The sync script uses name-based matching to update entries - if a name changes, it creates a new entry instead of updating
• The Devin API folder creation endpoint path is assumed (POST /knowledge/folders) - verify this is correct

Updates since last revision

• Reorganized scripts into scripts/devin/ subfolder with clearer names (per user request):
  • parse-local-knowledge.ts - parses local agents/ files
  • validate-local-knowledge.ts - validates local agents/ format
  • sync-knowledge-to-devin.ts - syncs to Devin API
  • export-devin-knowledge.ts - exports from Devin API (converted from shell to TypeScript)
• Updated path references to use ../.. since scripts are now two levels deep
• Added missing knowledge entries from Devin backup to knowledge-base.md (consolidated to avoid bloat):
  • E2E test skipping behavior and SAML CI errors in CI/CD section
  • Force push warning in git section
  • Factory function naming convention (Build[ServiceName]) in app-store section
  • New sections: DataTable, API documentation, round-robin scheduling, API v2 imports, code comments

Link to Devin run: https://app.devin.ai/sessions/b056870cc7fa42cbb2968159afa5929b
Requested by: @eunjae-lee

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[cubic-dev-ai]

2 issues found across 8 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="scripts/devin/sync-knowledge-to-devin.ts">

<violation number="1" location="scripts/devin/sync-knowledge-to-devin.ts:1">
P2: The shebang uses `env` with a multi-word command (`npx ts-node`), which fails when executing the script directly. Use a single executable (e.g., `ts-node`) or `env -S` to pass multiple args.</violation>
</file>

<file name="scripts/devin/validate-local-knowledge.ts">

<violation number="1" location="scripts/devin/validate-local-knowledge.ts:1">
P3: This shebang won’t run as an executable because `/usr/bin/env` can only take one argument; it will try to execute a command literally named `npx ts-node`. Use `env -S` (or a single command) so the script can be executed directly.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: The shebang uses env with a multi-word command (npx ts-node), which fails when executing the script directly. Use a single executable (e.g., ts-node) or env -S to pass multiple args.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/devin/sync-knowledge-to-devin.ts, line 1:

<comment>The shebang uses `env` with a multi-word command (`npx ts-node`), which fails when executing the script directly. Use a single executable (e.g., `ts-node`) or `env -S` to pass multiple args.</comment>

<file context>
@@ -0,0 +1,248 @@
+#!/usr/bin/env npx ts-node
+
+/**
</file context>

[cubic-dev-ai]

P3: This shebang won’t run as an executable because /usr/bin/env can only take one argument; it will try to execute a command literally named npx ts-node. Use env -S (or a single command) so the script can be executed directly.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/devin/validate-local-knowledge.ts, line 1:

<comment>This shebang won’t run as an executable because `/usr/bin/env` can only take one argument; it will try to execute a command literally named `npx ts-node`. Use `env -S` (or a single command) so the script can be executed directly.</comment>

<file context>
@@ -0,0 +1,174 @@
+#!/usr/bin/env npx ts-node
+
+/**
</file context>

_{Fix confidence (alpha): 8/10}

Suggested change

	#!/usr/bin/env npx ts-node
	#!/usr/bin/env -S npx ts-node

[github-actions]

Devin AI is addressing Cubic AI's review feedback

New feedback has been sent to the existing Devin session.

View Devin Session

---

✅ No changes pushed

[cubic-dev-ai]

1 issue found across 3 files (changes from recent commits).

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="scripts/devin/sync-knowledge-to-devin.ts">

<violation number="1" location="scripts/devin/sync-knowledge-to-devin.ts:10">
P3: Update the usage comment to reference the correct script path so the documented command is runnable.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[github-actions]

Devin AI is addressing Cubic AI's review feedback

New feedback has been sent to the existing Devin session.

View Devin Session

---

✅ Pushed commit 60b7440

[cubic-dev-ai]

3 issues found across 8 files

Prompt for AI agents (all issues)

Check if these issues are valid — if so, understand the root cause of each and fix them.


<file name="scripts/devin/parse-local-knowledge.ts">

<violation number="1" location="scripts/devin/parse-local-knowledge.ts:1">
P2: The shebang won’t execute because `/usr/bin/env` can’t resolve `npx ts-node` as a single binary. Use `env -S` or call `ts-node` directly so the script runs when executed as a file.</violation>
</file>

<file name="scripts/devin/export-devin-knowledge.ts">

<violation number="1" location="scripts/devin/export-devin-knowledge.ts:1">
P2: The shebang uses multiple arguments without `-S`, so direct execution will fail because `/usr/bin/env` receives `"npx tsx"` as a single program name. Use `env -S` or a single executable in the shebang.</violation>
</file>

<file name="scripts/devin/validate-local-knowledge.ts">

<violation number="1" location="scripts/devin/validate-local-knowledge.ts:1">
P2: The shebang is invalid because `/usr/bin/env` cannot take multiple arguments without `-S`. Running the script directly will fail. Use `-S` or a single executable in the shebang.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

P2: The shebang won’t execute because /usr/bin/env can’t resolve npx ts-node as a single binary. Use env -S or call ts-node directly so the script runs when executed as a file.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/devin/parse-local-knowledge.ts, line 1:

<comment>The shebang won’t execute because `/usr/bin/env` can’t resolve `npx ts-node` as a single binary. Use `env -S` or call `ts-node` directly so the script runs when executed as a file.</comment>

<file context>
@@ -0,0 +1,236 @@
+#!/usr/bin/env npx ts-node
+
+import * as fs from "fs";
</file context>

[cubic-dev-ai]

P2: The shebang is invalid because /usr/bin/env cannot take multiple arguments without -S. Running the script directly will fail. Use -S or a single executable in the shebang.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At scripts/devin/validate-local-knowledge.ts, line 1:

<comment>The shebang is invalid because `/usr/bin/env` cannot take multiple arguments without `-S`. Running the script directly will fail. Use `-S` or a single executable in the shebang.</comment>

<file context>
@@ -0,0 +1,174 @@
+#!/usr/bin/env npx ts-node
+
+/**
</file context>

_{Fix confidence (alpha): 8/10}

Suggested change

	#!/usr/bin/env npx ts-node
	#!/usr/bin/env -S npx ts-node

[github-actions]

Devin AI is addressing Cubic AI's review feedback

New feedback has been sent to the existing Devin session.

View Devin Session

---

✅ Pushed commit 0a3b0e1