docs: add OpenCode bootstrap context validation

[maxtechera]

Summary

• add an OpenCode parity bootstrap section to AGENTS.md so Claude workflow docs/config are treated as first-class context
• add .opencode/README.md documenting required config/docs directories and instruction precedence
• add scripts/validate-opencode-bootstrap.js plus pnpm opencode:validate-context to verify required bootstrap files/directories are present

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
answerai-docs	Building	Preview	Feb 19, 2026 9:42pm
the-answerai	Building	Preview	Feb 19, 2026 9:42pm

[claude]

PR Review: docs: add OpenCode bootstrap context validation

PR: #967 | Author: @maxtechera | Base: staging
Scope: 4 files changed, 165 additions, 0 deletions (pure additions - docs, script, and config)

---

Summary

This PR establishes a parity layer between Claude Code and OpenCode by documenting which configuration files OpenCode should treat as first-class context, and providing a validation script to verify that all required bootstrap files and directories are present. The changes are entirely documentation and developer tooling — no production code, business logic, routes, database queries, or authentication is touched.

Because this is a docs/tooling-only PR, the multi-tenancy (organizationId), authentication (enforceAbility), and component (tags: ['AAI']) checklists are not applicable here.

---

Critical Issues

None. There are no security vulnerabilities, data-handling issues, or breaking changes in this PR.

---

Major Concerns

1. Validation script will fail on a fresh clone

Location: scripts/validate-opencode-bootstrap.js, lines 20-29

Several directories listed as "required" are gitignored or not guaranteed to exist in all environments:

• .claude/examples/ - currently exists, but the validator would fail for contributors who have a partial checkout
• .claude/plans/ - exists in this repo but may not in forks
• .claude/implementation/ - ditto

More critically, .opencode/README.md is listed as a required file in the validator (line 17 of the script), but it is created by this very PR. This creates a circular dependency: the validator cannot pass on the staging branch until this PR is merged.

Recommendation: Consider separating "required for the tool to function" from "required as context hints for OpenCode". Directories like .claude/plans/ and .claude/implementation/ are team-internal working directories that may legitimately be absent in contributor forks.

2. process.exitCode vs process.exit() — exit may be deferred unexpectedly

Location: scripts/validate-opencode-bootstrap.js, lines 71-74

process.exitCode = 1

Using process.exitCode is generally correct for scripts that need to allow the event loop to drain. However, since this script is fully synchronous and there are no async operations, readers may be surprised that execution continues after setting exitCode = 1. This is not a bug, but the pattern can be confusing when the script grows. A short inline comment, or switching to process.exit(1) (since there is nothing async to flush), would improve clarity.

---

Minor Issues and Suggestions

3. .opencode/README.md does not include AGENTS.md in the required file list

Location: .opencode/README.md, lines 8-16

The AGENTS.md file is listed as a required file inside the validator script (scripts/validate-opencode-bootstrap.js, line 9) and in the AGENTS.md bootstrap section itself, but it is absent from the "Required Bootstrap Inputs" list in .opencode/README.md. These two sources are slightly out of sync.

For a reader consulting only .opencode/README.md, they would not know that AGENTS.md itself is a required input. The README should be updated to include AGENTS.md at the top of the required files list for consistency.

4. Precedence order differs in capitalisation and phrasing between files

Location: AGENTS.md line 31 vs .opencode/README.md line 38

In AGENTS.md:

4. package-level `CLAUDE.md` files

In .opencode/README.md:

4. Package-level `CLAUDE.md` files

Minor capitalisation inconsistency. Keeping these identical reduces ambiguity for tooling that may parse the precedence rules.

5. Script lacks a shebang-friendly description / usage comment

Location: scripts/validate-opencode-bootstrap.js, line 1

Other scripts in this repo (e.g., scripts/check-doc-versions.js) include a JSDoc block comment explaining the script's purpose, usage flags, and examples. The new script has a shebang but no header comment. Adding one would make it consistent and discoverable:

/**
 * OpenCode Bootstrap Validator
 *
 * Verifies that all files and directories required for OpenCode context
 * bootstrap are present in the repository.
 *
 * Usage: node scripts/validate-opencode-bootstrap.js
 *        pnpm opencode:validate-context
 */

6. Script output lacks ANSI colour for discoverability in terminals

Location: scripts/validate-opencode-bootstrap.js, throughout

Other validation scripts in this repo use ANSI colour codes to highlight PASS/FAIL/WARN states. For CI and local developer experience, coloured output makes the result immediately visible. This is a stylistic suggestion to match the existing script conventions.

7. opencode:validate-context script placement in package.json

Location: package.json, line 62

The new script is inserted after sync-docs and before secure-run. Grouping it near other developer/validation scripts (or at the end of the scripts block with a comment) would help future maintainers find it. This is a very minor nit.

---

Positive Observations

• The PR cleanly addresses a real gap: OpenCode users have no documented equivalent of Claude Code's CLAUDE.md-reading behaviour. This fills that gap with a single authoritative README.
• The validation script is a good addition to the developer tooling suite — it is lightweight, has zero dependencies (only Node.js built-ins), and produces actionable output.
• The precedence order documented in both AGENTS.md and .opencode/README.md is well-reasoned and consistent with how Claude Code itself handles conflicting instructions.
• The PR correctly targets staging, follows the project's commit message convention (docs: ...), and does not touch any production code paths.
• Adding pnpm opencode:validate-context to package.json makes the script discoverable without requiring contributors to know the exact file path.

---

TheAnswer-Specific Checklist

Check	Status
Multi-tenancy (organizationId on all DB queries)	N/A — no database code
Authentication (enforceAbility on all routes)	N/A — no route code
Error handling (InternalFlowiseError)	N/A — no server code
Component tags: ['AAI']	N/A — no component code
Database migrations	N/A — no schema changes
PR targets staging (not main)	PASS
Commit message follows convention	PASS

---

Next Steps

1. Address the sync issue in .opencode/README.md — add AGENTS.md to the required files list (minor, easy fix).
2. Consider whether directories like .claude/plans/ and .claude/implementation/ should be downgraded to optional, or document that they are expected to exist in all developer environments.
3. The PR is otherwise ready to merge once the minor README sync is addressed. No blocking issues.

[claude]

PR Review: docs: add OpenCode bootstrap context validation

PR: #967 | Author: @maxtechera | Base: staging | Commit: docs: add OpenCode config with instructions to CLAUDE files

---

Summary

This is a pure documentation and developer-tooling PR. It makes two small changes:

1. AGENTS.md — Prepends an index table (13 lines) that maps each key documentation file and directory to its purpose, giving OpenCode (and future AI tools) a single-glance orientation to the Claude workflow system.
2. opencode.json (new file, 13 lines) — Adds an OpenCode configuration file at the repository root that instructs OpenCode to load the same set of Claude workflow documents (AGENTS.md, CLAUDE.md, .claude/README.md, .claude/ARCHITECTURE.md, and all files under .claude/commands/, .claude/agents/, .claude/skills/, .claude/rules/) as first-class context.

No production code, business logic, API routes, database queries, authentication, or component logic is touched. The PR body references a validation script and .opencode/README.md, but neither of those files appears in the current diff — only the two files above are actually changed.

---

Critical Issues

None. There are no security vulnerabilities, no data-handling concerns, and no breaking changes.

---

Major Concerns

1. PR description is out of sync with the actual diff

Location: PR body

The PR summary describes three deliverables: a bootstrap section in AGENTS.md, an .opencode/README.md file, and a scripts/validate-opencode-bootstrap.js script with a corresponding pnpm opencode:validate-context entry in package.json. However, the actual diff contains only two files: the AGENTS.md index table and opencode.json. The script, the .opencode/README.md, and the package.json script are absent.

This creates ambiguity for reviewers: it is unclear whether those items were intentionally dropped, are coming in a follow-up PR, or were accidentally left off the branch. Updating the PR description to match what is actually being merged would eliminate the confusion.

2. opencode.json references .claude/ARCHITECTURE.md, which is not listed in the AGENTS.md index

Location: opencode.json line 7; AGENTS.md index table (lines 4–14)

opencode.json lists .claude/ARCHITECTURE.md as an instruction file. The AGENTS.md index table — the human-facing key to what OpenCode will load — does not mention it. The file does exist (560 lines of content), so there is no functional problem, but a reader consulting AGENTS.md to understand the full OpenCode context set will have an incomplete picture. Adding a row for .claude/ARCHITECTURE.md to the index would keep both files in sync.

---

Minor Issues and Suggestions

3. Index table row for .claude/agents/*.md understates coverage

Location: AGENTS.md index table, row 6

The current description is "Specialized agents (Linear, Git, Fleet)". There are now 24 agent files in .claude/agents/, covering Linear ticket workflows, fleet orchestration, blog writing, GitHub issue triage, spec maintenance, integration validation, and PR review. A broader description such as "Autonomous agent definitions for all workflow types" would be more accurate for first-time readers.

4. Index table does not acknowledge .claude/docs/

Location: AGENTS.md index table

The .claude/docs/ directory contains walkthrough and research documents (e.g., FLEET-AGENT-TEAMS-WALKTHROUGH.md, PARALLEL-AGENT-ORCHESTRATION.md). These are not loaded by opencode.json, so omitting them from the index is reasonable. A brief note — either as a comment in opencode.json or a parenthetical in the AGENTS.md section — clarifying that .claude/docs/ is intentionally excluded would prevent a future contributor from treating the omission as an oversight.

5. Branch name prefix does not match commit type

Location: Branch chore/opencode-bootstrap-context, commit docs: add OpenCode config with instructions to CLAUDE files

The commit message correctly uses docs: per the project convention; the branch prefix chore/ is slightly mismatched. This has no practical impact, but future branches of this type would be more consistent as docs/opencode-bootstrap-context.

---

Positive Observations

• Correctly targets staging, not main. No convention violations.
• The commit message follows the project type: description format (docs:).
• Using a $schema reference in opencode.json is good practice — it enables editor validation and auto-completion for anyone editing the file.
• The index table in AGENTS.md is a genuine usability improvement. It gives both human contributors and AI tools a structured entry point rather than requiring a linear read of the entire file.
• The glob patterns in opencode.json (*.md) are appropriately broad — any new command, agent, skill, or rule file added in future will automatically be included in OpenCode's context without a config update.
• Co-locating opencode.json at the repository root mirrors where CLAUDE.md lives, making it discoverable by convention.
• No production code paths are affected; the change is entirely additive and zero-risk for the application.

---

TheAnswer-Specific Checklist

Check	Status
Multi-tenancy (organizationId on all DB queries)	N/A — no database code
Authentication (enforceAbility on all routes)	N/A — no route code
Error handling (InternalFlowiseError)	N/A — no server code
Component tags ['AAI']	N/A — no Flowise component code
Database migrations required	N/A — no schema changes
PR targets staging (not main)	PASS
Commit message follows convention	PASS
No sensitive data exposed	PASS

---

Overall Recommendation

Comment — approve with minor suggestions

The change is safe, additive, and addresses a real gap in developer-tooling parity between Claude Code and OpenCode. Two items are worth addressing before merge:

1. Update the PR description to accurately reflect the diff (the script and .opencode/README.md mentioned in the body are not present in this branch).
2. Add a row for .claude/ARCHITECTURE.md to the AGENTS.md index table so it matches what opencode.json actually loads.

Neither is a hard blocker, but both would make the PR self-consistent and easier to understand in the git history.