docs: document brainstorm agent (Phase 0) in orion-docs#7
Merged
dmicheneau merged 5 commits intoharnessfrom Apr 7, 2026
Merged
docs: document brainstorm agent (Phase 0) in orion-docs#7dmicheneau merged 5 commits intoharnessfrom
dmicheneau merged 5 commits intoharnessfrom
Conversation
The brainstorm agent had correct write permissions for docs/briefs/** in index.js but the directory did not exist on disk. OpenCode's write tool requires the parent directory to exist — the missing directory caused a permissions-like error at runtime. - Add docs/briefs/.gitkeep so the directory persists after git clone - Remove erroneous todowrite: allow that was added during the fix attempt (brainstorm agent never uses todowrite)
…re, and CI enforcement - Add adversarial gate (mandatory before Phase 3): agent synthesizes the strongest case against building the project and asks what would cause it to fail in year one - Add Socratic pressure in Phase 1 and Phase 2: agent challenges stated assumptions and constraints once before accepting them - Hard-block on incomplete briefs: missing Problem, Success Criteria, or Scope In blocks the brief from being written - Scope inflation detection: flagged once when in-scope list hits 5+ items - Early name check in Phase 2: file conflict surfaced immediately, not at Phase 3 after a full session - Convergence rule: cosmetic disagreements noted as open questions; substantive ones block output entirely - Add brief-schema CI check: validates required frontmatter fields and section headings on all docs/briefs/*.md files - Add no-permissions-in-agent-prompts CI check: forbids ## Permissions sections in agents/*.md (permissions live exclusively in index.js) - Remove ## Permissions section from agents/brainstorm.md and docs/specs/brainstorm-agent.md (caught by new CI check) - Update guiding-principles.md with two new principles - Update website (App.tsx + bundle.html) to reflect new brainstorm workflow
Encodes the pattern exposed by the brainstorm agent bug: a write/edit permission path declared in index.js is useless if the target directory doesn't exist on disk — the agent silently fails at runtime. - Add agent-write-dirs-exist CI check: parses write/edit allow paths from index.js, extracts base directories, and verifies they exist in the repo - Add docs/exec-plans/.gitkeep: planning agent had the same missing directory issue (docs/exec-plans/ declared but never created) - Add guiding principle: declared write/edit target directories must exist and be tracked with .gitkeep or real content - Update AGENTS.md enforcement table with the new check
The bash CI job that verified write/edit target directories exist is replaced by a proper unit test in tests/permissions.test.js. The test suite (node:test, zero deps) was already in place on the harness branch. - Add tests/permissions.test.js: parses index.js, extracts all write/edit allow paths ending in /**, strips the glob suffix, and asserts each base directory exists on disk - Remove agent-write-dirs-exist job from checks.yml
azrod
pushed a commit
that referenced
this pull request
May 4, 2026
* fix: create docs/briefs/ directory so brainstorm agent can write briefs The brainstorm agent had correct write permissions for docs/briefs/** in index.js but the directory did not exist on disk. OpenCode's write tool requires the parent directory to exist — the missing directory caused a permissions-like error at runtime. - Add docs/briefs/.gitkeep so the directory persists after git clone - Remove erroneous todowrite: allow that was added during the fix attempt (brainstorm agent never uses todowrite) * feat: improve brainstorm agent with adversarial gate, Socratic pressure, and CI enforcement - Add adversarial gate (mandatory before Phase 3): agent synthesizes the strongest case against building the project and asks what would cause it to fail in year one - Add Socratic pressure in Phase 1 and Phase 2: agent challenges stated assumptions and constraints once before accepting them - Hard-block on incomplete briefs: missing Problem, Success Criteria, or Scope In blocks the brief from being written - Scope inflation detection: flagged once when in-scope list hits 5+ items - Early name check in Phase 2: file conflict surfaced immediately, not at Phase 3 after a full session - Convergence rule: cosmetic disagreements noted as open questions; substantive ones block output entirely - Add brief-schema CI check: validates required frontmatter fields and section headings on all docs/briefs/*.md files - Add no-permissions-in-agent-prompts CI check: forbids ## Permissions sections in agents/*.md (permissions live exclusively in index.js) - Remove ## Permissions section from agents/brainstorm.md and docs/specs/brainstorm-agent.md (caught by new CI check) - Update guiding-principles.md with two new principles - Update website (App.tsx + bundle.html) to reflect new brainstorm workflow * harness: enforce that agent write/edit target directories exist in repo Encodes the pattern exposed by the brainstorm agent bug: a write/edit permission path declared in index.js is useless if the target directory doesn't exist on disk — the agent silently fails at runtime. - Add agent-write-dirs-exist CI check: parses write/edit allow paths from index.js, extracts base directories, and verifies they exist in the repo - Add docs/exec-plans/.gitkeep: planning agent had the same missing directory issue (docs/exec-plans/ declared but never created) - Add guiding principle: declared write/edit target directories must exist and be tracked with .gitkeep or real content - Update AGENTS.md enforcement table with the new check * test: replace agent-write-dirs-exist CI check with unit test The bash CI job that verified write/edit target directories exist is replaced by a proper unit test in tests/permissions.test.js. The test suite (node:test, zero deps) was already in place on the harness branch. - Add tests/permissions.test.js: parses index.js, extracts all write/edit allow paths ending in /**, strips the glob suffix, and asserts each base directory exists on disk - Remove agent-write-dirs-exist job from checks.yml * docs: update orion-docs to document brainstorm agent (Phase 0)
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.
Résumé
Met à jour le site de documentation
orion-docspour documenter précisément l'agentbrainstorm(Phase 0) en se basant sur son comportement réel défini dansagents/brainstorm.md.Changements
brainstorm (Phase 0)comme nœud en amont d'Orion avec deux chemins : "si découverte produit" et "sinon demande directe"read (tous fichiers)(incorrect), ajout dewebfetch. La lecture est déléguée à un sous-agentexploreviatask.sectionComponentsremplacé parrenderSection()pour éviter le reset d'état des onglets à chaque navigationresizable.tsx— Compatibilitéreact-resizable-panelsv4 (PanelGroup→Group,PanelResizeHandle→Separator)bundle.htmlrégénéré