feat: add Codex integration with bootstrap and knowledge templates by frontlook-admin · Pull Request #1039 · bradygaster/squad

frontlook-admin · 2026-04-25T06:22:15Z

What

This PR adds Codex bootstrap/support files and wiring so newly initialized or upgraded Squad repos automatically get Codex-specific templates and metadata without overwriting user-owned files.

Why

This enables Codex to work as a first-class local implementation coordinator in Squad-based repos by ensuring the required bootstrap, operating profile, shared knowledge, and agent charter/history files are present. It also updates generated team metadata so Codex appears as an active squad member.

How

The change introduces new Codex template files in the shared template roots, registers them in the CLI template manifest, and adds upgrade/init logic to copy them only when missing. It also extends initSquad() team generation to include Codex in team.md, and adds tests covering both init-time creation and upgrade-time non-destructive setup behavior.

⚠️ Quick Check

If SDK/CLI source files changed: completed the applicable Changeset step below (npx changeset add / .changeset/*.md, direct CHANGELOG.md entry for maintainers, or skip-changelog label for no user-facing changes)

PR Readiness Checklist

The PR readiness bot will validate these automatically after push.
Check each item before requesting review. See CONTRIBUTING.md for full details.

Branch & Commit

Branch created from dev (not main)
Branch is up to date with dev (git fetch upstream && git rebase upstream/dev)
Verified diff contains only intended changes (git diff --cached --stat)
PR is not in draft mode (mark ready when checks pass)
Commit history is clean (squash fixups before review)

Build & Test

npm run build passes
npm test passes (all tests green)
npm run lint passes (type check clean)
npm run lint:eslint passes
For migration PRs (>20 files): include test output summary in PR description

Changeset

Changeset added via npx changeset add (if packages/squad-sdk/src/ or packages/squad-cli/src/ changed)
Or direct CHANGELOG.md entry (maintainers only — write-protected for external contributors)
Or skip-changelog label applied (if no user-facing changes)

Docs

README section updated (if new feature/module)
Docs feature page (if new user-facing capability)

Exports

package.json subpath exports updated (if new module)

Breaking Changes

None

Waivers

None

Copilot

Pull request overview

Adds first-class Codex integration to Squad initialization and upgrade flows by shipping Codex-specific bootstrap/knowledge/agent templates and ensuring they are created only when missing (non-destructive to user-owned files).

Changes:

Add Codex template files (bootstrap, operating profile, shared knowledge, charter/history) across all template roots.
Extend SDK initSquad() to generate Codex entries in team.md and copy Codex files if missing.
Extend CLI upgrade to backfill missing Codex setup files and add tests for init/upgrade behavior.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
test/init-scaffolding.test.ts	Adds SDK init coverage for Codex bootstrap + shared knowledge file creation.
test/cli/upgrade.test.ts	Adds upgrade coverage for creating missing Codex setup files without overwriting `AGENTS.md`.
templates/shared-knowledge.md	Root template for shared, durable Codex/Squad project knowledge.
templates/codex.md	Root template for Codex operating profile.
templates/codex-bootstrap.md	Root template for Codex bootstrap content (mirrors to `AGENTS.md`).
templates/agents/codex/history.md	Root template for Codex agent history.
templates/agents/codex/charter.md	Root template for Codex agent charter.
packages/squad-sdk/templates/shared-knowledge.md	SDK-shipped copy of shared knowledge template.
packages/squad-sdk/templates/codex.md	SDK-shipped copy of Codex operating profile template.
packages/squad-sdk/templates/codex-bootstrap.md	SDK-shipped copy of Codex bootstrap template.
packages/squad-sdk/templates/agents/codex/history.md	SDK-shipped copy of Codex history template.
packages/squad-sdk/templates/agents/codex/charter.md	SDK-shipped copy of Codex charter template.
packages/squad-sdk/src/config/init.ts	Adds Codex template copy-on-missing + injects Codex rows into generated `team.md`.
packages/squad-cli/templates/shared-knowledge.md	CLI-shipped copy of shared knowledge template.
packages/squad-cli/templates/codex.md	CLI-shipped copy of Codex operating profile template.
packages/squad-cli/templates/codex-bootstrap.md	CLI-shipped copy of Codex bootstrap template.
packages/squad-cli/templates/agents/codex/history.md	CLI-shipped copy of Codex history template.
packages/squad-cli/templates/agents/codex/charter.md	CLI-shipped copy of Codex charter template.
packages/squad-cli/src/cli/core/upgrade.ts	Adds `ensureCodexSetup()` to create missing Codex files during upgrade without overwriting existing ones.
packages/squad-cli/src/cli/core/templates.ts	Registers Codex templates in the CLI manifest as user-owned (never overwrite).
.squad-templates/shared-knowledge.md	Canonical template copy for sync across template roots.
.squad-templates/codex.md	Canonical template copy for sync across template roots.
.squad-templates/codex-bootstrap.md	Canonical template copy for sync across template roots.
.squad-templates/agents/codex/history.md	Canonical template copy for sync across template roots.
.squad-templates/agents/codex/charter.md	Canonical template copy for sync across template roots.

Copilot · 2026-04-25T06:27:07Z

+const CODEX_TEMPLATE_FILES = [
+  {
+    templateName: 'codex-bootstrap.md',
+    destination: 'AGENTS.md',
+  },
+  {
+    templateName: 'codex.md',
+    destination: join('.squad', 'codex.md'),
+  },
+  {
+    templateName: 'shared-knowledge.md',
+    destination: join('.squad', 'shared-knowledge.md'),
+  },
+  {
+    templateName: join('agents', 'codex', 'charter.md'),
+    destination: join('.squad', 'agents', 'codex', 'charter.md'),
+  },
+  {
+    templateName: join('agents', 'codex', 'history.md'),
+    destination: join('.squad', 'agents', 'codex', 'history.md'),
+  },
+] as const;
+
 export async function initSquad(options: InitOptions, storage: StorageProvider = new FSStorageProvider()): Promise<InitResult> {


This PR modifies both packages/squad-sdk/src/** and packages/squad-cli/src/**, but there doesn’t appear to be a corresponding Changeset entry. Please add a .changeset/*.md (or apply the skip-changelog label if this is intentionally non-user-facing) to satisfy the repo’s changelog gate.

Copilot · 2026-04-25T06:27:07Z


 | Name | Role | Charter | Status |
 |------|------|---------|--------|
+| Codex | Local Implementation Coordinator | \`.squad/agents/codex/charter.md\` | Active |


The Codex role text is inconsistently capitalized between the Coordinator table and Members table ("Local implementation coordinator" vs "Local Implementation Coordinator"). Please make the role string consistent to avoid confusing generated team metadata and downstream parsing/grepping.

Suggested change

| Codex | Local Implementation Coordinator | \`.squad/agents/codex/charter.md\` | Active |

| Codex | Local implementation coordinator | \`.squad/agents/codex/charter.md\` | Active |

Copilot · 2026-04-25T06:27:07Z

+    const customAgents = '# Custom Codex Bootstrap\n';
+
+    await writeFile(agentsPath, customAgents);
+    await rm(codexPath, { force: true });
+    await rm(sharedKnowledgePath, { force: true });
+    await rm(codexCharterPath, { force: true });
+
+    await runUpgrade(TEST_ROOT);
+
+    expect(await readFile(agentsPath, 'utf-8')).toBe(customAgents);
+    expect(existsSync(codexPath)).toBe(true);
+    expect(existsSync(sharedKnowledgePath)).toBe(true);
+    expect(existsSync(codexCharterPath)).toBe(true);


This test only verifies non-overwrite behavior for AGENTS.md, but the new upgrade behavior also promises not to overwrite .squad/codex.md, .squad/shared-knowledge.md, and .squad/agents/codex/*. Consider extending the test to (1) seed custom content in those files, (2) run runUpgrade(), and (3) assert the custom content is preserved, and also assert history.md is created when missing.

Suggested change

const customAgents = '# Custom Codex Bootstrap\n';

await writeFile(agentsPath, customAgents);

await rm(codexPath, { force: true });

await rm(sharedKnowledgePath, { force: true });

await rm(codexCharterPath, { force: true });

await runUpgrade(TEST_ROOT);

expect(await readFile(agentsPath, 'utf-8')).toBe(customAgents);

expect(existsSync(codexPath)).toBe(true);

expect(existsSync(sharedKnowledgePath)).toBe(true);

expect(existsSync(codexCharterPath)).toBe(true);

const historyPath = join(TEST_ROOT, '.squad', 'history.md');

const customAgents = '# Custom Codex Bootstrap\n';

const customCodex = '# Custom Codex Guide\n';

const customSharedKnowledge = '# Custom Shared Knowledge\n';

const customCodexCharter = '# Custom Codex Charter\n';

await writeFile(agentsPath, customAgents);

await writeFile(codexPath, customCodex);

await writeFile(sharedKnowledgePath, customSharedKnowledge);

await writeFile(codexCharterPath, customCodexCharter);

await rm(historyPath, { force: true });

await runUpgrade(TEST_ROOT);

expect(await readFile(agentsPath, 'utf-8')).toBe(customAgents);

expect(await readFile(codexPath, 'utf-8')).toBe(customCodex);

expect(await readFile(sharedKnowledgePath, 'utf-8')).toBe(customSharedKnowledge);

expect(await readFile(codexCharterPath, 'utf-8')).toBe(customCodexCharter);

expect(existsSync(historyPath)).toBe(true);

Copilot · 2026-04-25T06:27:08Z

+  it('creates Codex bootstrap and shared knowledge files', async () => {
+    await initSquad(sdkOptions(TEST_ROOT));
+
+    expect(existsSync(join(TEST_ROOT, 'AGENTS.md'))).toBe(true);
+    expect(existsSync(join(TEST_ROOT, '.squad', 'codex.md'))).toBe(true);
+    expect(existsSync(join(TEST_ROOT, '.squad', 'shared-knowledge.md'))).toBe(true);
+    expect(existsSync(join(TEST_ROOT, '.squad', 'agents', 'codex', 'charter.md'))).toBe(true);
+    expect(existsSync(join(TEST_ROOT, '.squad', 'agents', 'codex', 'history.md'))).toBe(true);
+
+    const team = await readFile(join(TEST_ROOT, '.squad', 'team.md'), 'utf-8');
+    expect(team).toContain('Codex');
+    expect(team).toContain('.squad/agents/codex/charter.md');
+  });


Init-time coverage here only exercises the SDK initSquad() path. Since this PR also wires Codex templates through the CLI template manifest, it would be good to add a corresponding assertion in the runInit() section that AGENTS.md, .squad/codex.md, and .squad/shared-knowledge.md are created (and not overwritten on re-run).

bradygaster · 2026-04-25T20:30:21Z

@frontlook-admin is the idea for this to expose Squad to a non-Copilot SDK? We've closed a variety of former issues as we explicitly don't intend on exposing Squad to other SDKs.

frontlook-admin · 2026-04-26T04:58:59Z

@bradygaster yes, thats the idea. actually, given the current scenario of copilot daily and weekly limits, I felt squad should also work for other non-copilot environments, or if not everything, atleast knowledge gained by squad can be shared.

feat: add Codex integration with bootstrap and knowledge templates

a1f7ac8

Copilot AI review requested due to automatic review settings April 25, 2026 06:22

Copilot started reviewing on behalf of frontlook-admin April 25, 2026 06:22 View session

Copilot AI reviewed Apr 25, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: add Codex integration with bootstrap and knowledge templates#1039

feat: add Codex integration with bootstrap and knowledge templates#1039
frontlook-admin wants to merge 1 commit intobradygaster:devfrom
frontlook-admin:Alpha

frontlook-admin commented Apr 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

Copilot AI Apr 25, 2026

Uh oh!

bradygaster commented Apr 25, 2026

Uh oh!

frontlook-admin commented Apr 26, 2026 •

edited

Loading

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	\| Codex \| Local Implementation Coordinator \| \`.squad/agents/codex/charter.md\` \| Active \|
	\| Codex \| Local implementation coordinator \| \`.squad/agents/codex/charter.md\` \| Active \|

Conversation

frontlook-admin commented Apr 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

How

⚠️ Quick Check

PR Readiness Checklist

Branch & Commit

Build & Test

Changeset

Docs

Exports

Breaking Changes

Waivers

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 25, 2026

Choose a reason for hiding this comment

Uh oh!

bradygaster commented Apr 25, 2026

Uh oh!

frontlook-admin commented Apr 26, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

frontlook-admin commented Apr 25, 2026 •

edited

Loading

frontlook-admin commented Apr 26, 2026 •

edited

Loading