feat(codex): add bootstrap.js for Codex local skills (squad chiefs) [Story 123.9]#641
Open
rafaelscosta wants to merge 1 commit intomainfrom
Open
feat(codex): add bootstrap.js for Codex local skills (squad chiefs) [Story 123.9]#641rafaelscosta wants to merge 1 commit intomainfrom
rafaelscosta wants to merge 1 commit intomainfrom
Conversation
…Story 123.9] Definitive solution for the bug where squad-chief skills did not appear in Codex's $ menu. Root cause: existing sync:skills:codex (index.js) only generates skills from .aiox-core/development/agents/, leaving squad chiefs in squads/*/agents/ uncovered. Implementation: - New: .aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js Standalone, zero-deps (vendored js-yaml fallback). Generates aiox-* skills for both core agents AND squad entry chiefs via config.yaml resolution (entry_agent | tier=orchestrator | *-chief.md). Marker-aware (skips hand-edited skills unless --force, with .bak backup). - New: README.md — explains the difference between sync:skills:codex (incremental, core-only, CI) and setup:codex-skills (full bootstrap, squad chiefs included, operator-facing). - package.json: setup:codex-skills, setup:codex-skills:dry scripts. - Sample output: .codex/skills/aiox-claude-mastery-chief/SKILL.md (only squad whitelisted in this repo; downstream installs with N squads will get N chief skills). Operator usage: npm run setup:codex-skills # full bootstrap npm run setup:codex-skills:dry # preview npm run setup:codex-skills -- --force # overwrite hand-edited (with .bak) Replaces the provisional standalone script previously distributed manually to students. The script logic is preserved verbatim; only the header doc and module exports were adapted for the canonical path. Note: bootstrap.js sits under .aiox-core/infrastructure/scripts/ which is in eslint global ignore, so no lint impact. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rafaelscosta
requested review from
Pedrovaleriolopez and
oalanicolas
as code owners
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
WalkthroughIntroduces Codex Skills Sync tooling that generates local skills from AIOX core agents and squad definitions. A bootstrap script scans agent and squad source files, parses YAML configurations, and outputs standardized SKILL.md files to Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
github-actions
Bot
added
area: agents
Contributor
📊 Coverage ReportCoverage report not available
Generated by PR Automation (Story 6.1) |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
🧹 Nitpick comments (5)
.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js (3)
659-669: Consider warning when YAML parser is unavailable.When
loadYamlreturnsnull, the script continues with regex-based extraction only. While this graceful degradation is intentional, a warning would help operators understand why some metadata might be incomplete.💡 Suggested enhancement
const yaml = loadYaml(projectRoot); +if (!yaml && !args.quiet) { + console.warn('Warning: js-yaml not found. Metadata extraction will be limited to regex patterns.'); +} const corePlans = buildCorePlans(projectRoot, yaml);🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js around lines 659 - 669, The code currently proceeds when loadYaml(projectRoot) returns null, which can hide missing metadata; update the bootstrapping flow to detect when yaml === null after calling loadYaml and emit a clear warning before continuing with regex-only extraction (use an existing logger like processLogger.warn if present, falling back to console.warn) so operators know metadata may be incomplete; locate the loadYaml call and the subsequent buildCorePlans/buildSquadPlans/dedupePlans sequence and add the warning immediately after the loadYaml(projectRoot) assignment.
440-457: Complex but necessary skill ID resolution logic.The
squadSkillIdfunction handles multiple edge cases for generating unique skill IDs. The logic is sound:
- Avoids
aiox-aiox-prefixes- Handles squad names that embed entry agent names
- Falls back to
aiox-<squad>-<entry>for disambiguationConsider adding inline comments explaining each branch for future maintainers.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js around lines 440 - 457, Add short inline comments inside the squadSkillId function to explain the purpose of each computed variable and every conditional branch: document why alias/squadBase/entry/entryRoot are derived, why we return coreSkillId when entry is missing, why we return `aiox-${entry}` when entry matches or is prefixed by squadBase or alias, why genericEntryRoots are excluded and the special handling for entryRoot prefixes and `-chief` suffixes, and why the final fallback returns `aiox-${squadBase || alias}-${entry}` to disambiguate; place these comments next to the variables (alias, squadBase, entry, entryRoot, genericEntryRoots) and before each if/return to aid future maintainers.
202-213: Consider adding input length bounds for block scalar parsing.The
findBlockScalarregex handles multiline YAML block scalars. While the pattern is anchored and uses bounded groups, extremely large input files could still cause performance degradation. For production-grade robustness, consider limiting input size or adding a timeout mechanism, though this is likely acceptable for typical agent file sizes.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js around lines 202 - 213, The findBlockScalar function can exhibit poor performance on extremely large inputs; add a defensive input-size guard (e.g., MAX_BLOCK_SCALAR_INPUT) and bail or truncate early inside findBlockScalar when text.length exceeds that threshold, or add an optional parameter (maxLength) to limit how much of text is scanned; ensure the guard runs before constructing the RegExp/match to avoid catastrophic backtracking on huge payloads and document/handle the trimmed result consistently in findBlockScalar's return path..aiox-core/infrastructure/scripts/codex-skills-sync/README.md (2)
18-23: Add language specifiers to fenced code blocks.The fenced code blocks at lines 18, 39, and 48 lack language specifiers. Adding
bashorshellimproves syntax highlighting and satisfies markdown lint rules.📝 Suggested fix
-``` +```bash npm run setup:codex-skills # generate / updateApply similarly to the other code blocks.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.aiox-core/infrastructure/scripts/codex-skills-sync/README.md around lines 18 - 23, The fenced code blocks in the README lack language specifiers; update each opening triple-backtick for the blocks containing the commands (the block with "npm run setup:codex-skills", "npm run setup:codex-skills:dry", and the block with "node bootstrap.js --force" / "node bootstrap.js --help") to include a shell/bash specifier (e.g., ```bash) so markdown linting and syntax highlighting are satisfied.
69-70: Missing newline at end of file.Line 70 appears to be missing the trailing newline character, which is a common convention for text files.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.aiox-core/infrastructure/scripts/codex-skills-sync/README.md around lines 69 - 70, The README.md file ends without a trailing newline (the final paragraph beginning "Background: students reported that squad-chief skills..." is missing the EOF newline); update the file to ensure a newline character is present at the end of the file so the file ends with a single trailing newline.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js:
- Around line 659-669: The code currently proceeds when loadYaml(projectRoot)
returns null, which can hide missing metadata; update the bootstrapping flow to
detect when yaml === null after calling loadYaml and emit a clear warning before
continuing with regex-only extraction (use an existing logger like
processLogger.warn if present, falling back to console.warn) so operators know
metadata may be incomplete; locate the loadYaml call and the subsequent
buildCorePlans/buildSquadPlans/dedupePlans sequence and add the warning
immediately after the loadYaml(projectRoot) assignment.
- Around line 440-457: Add short inline comments inside the squadSkillId
function to explain the purpose of each computed variable and every conditional
branch: document why alias/squadBase/entry/entryRoot are derived, why we return
coreSkillId when entry is missing, why we return `aiox-${entry}` when entry
matches or is prefixed by squadBase or alias, why genericEntryRoots are excluded
and the special handling for entryRoot prefixes and `-chief` suffixes, and why
the final fallback returns `aiox-${squadBase || alias}-${entry}` to
disambiguate; place these comments next to the variables (alias, squadBase,
entry, entryRoot, genericEntryRoots) and before each if/return to aid future
maintainers.
- Around line 202-213: The findBlockScalar function can exhibit poor performance
on extremely large inputs; add a defensive input-size guard (e.g.,
MAX_BLOCK_SCALAR_INPUT) and bail or truncate early inside findBlockScalar when
text.length exceeds that threshold, or add an optional parameter (maxLength) to
limit how much of text is scanned; ensure the guard runs before constructing the
RegExp/match to avoid catastrophic backtracking on huge payloads and
document/handle the trimmed result consistently in findBlockScalar's return
path.
In @.aiox-core/infrastructure/scripts/codex-skills-sync/README.md:
- Around line 18-23: The fenced code blocks in the README lack language
specifiers; update each opening triple-backtick for the blocks containing the
commands (the block with "npm run setup:codex-skills", "npm run
setup:codex-skills:dry", and the block with "node bootstrap.js --force" / "node
bootstrap.js --help") to include a shell/bash specifier (e.g., ```bash) so
markdown linting and syntax highlighting are satisfied.
- Around line 69-70: The README.md file ends without a trailing newline (the
final paragraph beginning "Background: students reported that squad-chief
skills..." is missing the EOF newline); update the file to ensure a newline
character is present at the end of the file so the file ends with a single
trailing newline.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 4fc1a6bb-0edb-485c-8e2b-4961bf345d9c
📒 Files selected for processing (5)
.aiox-core/infrastructure/scripts/codex-skills-sync/README.md.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js.aiox-core/install-manifest.yaml.codex/skills/aiox-claude-mastery-chief/SKILL.mdpackage.json
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Story 123.9 — Definitive solution for "Codex skills not loading" bug.
Background: Students reported that squad-chief skills (e.g.
mega-brain-chief,slides-chief,brand-chief) did not appear in Codex's$menu. A provisional standalone script (setup-codex-local-skills.js) was distributed manually as a workaround. This PR vendors that script as the canonical bootstrap.Root cause: The existing
npm run sync:skills:codex(codex-skills-sync/index.js) only generates skills from.aiox-core/development/agents/(12 core agents). Squad chiefs insquads/*/agents/were never covered.Implementation
New:
.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js(727 LOC)aiox-*skills for both core agents and squad entry chiefsentry_agentfield →tier: orchestrator→*-chief.mdheuristic--force(which creates.bak)js-yamlfallback for resilience.aiox-core/infrastructure/scripts/codex-skills-sync/README.md— explains the difference betweensync:skills:codex(incremental, CI) andsetup:codex-skills(full bootstrap)package.json:setup:codex-skills+setup:codex-skills:dryscripts.codex/skills/aiox-claude-mastery-chief/SKILL.md(the only squad whitelisted in this repo'ssquads/)Why a separate script (not a refactor of
index.js)sync:skills:codex(index.js)setup:codex-skills(bootstrap.js)Refactoring
index.jsto also handle squads would require extending the sharedagent-parser.jsfromide-sync/to parseconfig.yaml+ entry-agent resolution — a larger surface change.bootstrap.jsis a focused, opt-in operator command. The two coexist cleanly.Operator usage
After running, restart Codex CLI from the project root if the
$menu does not refresh automatically.Verification
node bootstrap.js --dry-run: discovers 12 core skills + 1 squad entry skill (onlyclaude-code-masteryis whitelisted insquads/for this repo)node bootstrap.js(real run): 12 coreskipped_existing(preserves existing hand-edits), 1 squadcreated(aiox-claude-mastery-chief)npm run setup:codex-skills:dryworksbootstrap.jslives under.aiox-core/infrastructure/scripts/(eslint global ignore) — no lint impactMigration / replaces
This commit replaces the provisional standalone script previously distributed to students with instructions "drop in project root and run
node setup-codex-local-skills.js". Students should now runnpm run setup:codex-skills. Update the operator handoff (docs/guides/supabase-ops-handoff.md, owned by Story 123.8) to reflect the new command — that update can land as a follow-up.🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Documentation