docs: expand Phase 0 brainstorm flowchart with full entry logic#8
Closed
dmicheneau wants to merge 15 commits intomainfrom
Closed
docs: expand Phase 0 brainstorm flowchart with full entry logic#8dmicheneau wants to merge 15 commits intomainfrom
dmicheneau wants to merge 15 commits intomainfrom
Conversation
- harness: full bash/read/write/edit permissions for enforcement artifact creation - planning: exec-plan writing scoped to docs/exec-plans/ - gardener: maintenance agent with scoped git/gh bash access - Remove memory.md concept — scratchpad-only persistence going forward - bug-finder gains pattern detection and harness escalation recommendation - Add docs/ with architecture, ADRs, specs, templates, and background research
… context-aware PR logic
* feat: add brainstorm agent for product brief discovery
Introduces a Phase 0 brainstorm agent that helps users discover and articulate what they want to build before planning starts. The agent runs a 3-phase conversational flow (Discovery → Deep dive → Draft + validation), produces a structured product brief at docs/briefs/{project-name}.md, and hands off cleanly to the Planning agent or Orion.
- Temperature 0.5 for open-ended discovery, mode: all
- Write permission scoped to docs/briefs/** only
- Session resume logic: scans for status:draft files on open
- Quality gate with Tier 1 (auto-fix) and Tier 2 (user-blocking) split
* docs: update all documentation and website for brainstorm agent
Add brainstorm to docs/index.md agent table, docs/architecture.md (diagram, agent table, permissions, prompt loading), README.md (bullet + dedicated section), docs/specs/orion-delegation.md, and the team-lead-workflow website (EN + FR agents and config_agent_defaults arrays). Fix TypeScript compatibility in resizable.tsx (react-resizable-panels v4 API). Rebuild bundle.html.
* chore: remove example brief from brainstorm test
* fix: address Copilot review comments on brainstorm agent PR
… flag
- Rename `permissions` to `permission` (silent bug — key was ignored by registerSubagent)
- Replace `read: "allow"` with `read: { "*": "allow" }` for consistent merge behavior
- Remove `silent: true` — reserved for internal sub-agents, not user-facing agents
…nt specs - AGENTS.md restructured as a navigation index with pointers to docs/ rather than duplicating architecture content; removed memory.md and experimental.chat.system.transform references; updated file count - docs/architecture.md: remove deprecated system.transform hook and memory.md references; add harness, planning, gardener to agent table - README.md: full rewrite — all 10 agents documented, accurate permissions table, memory.md references removed - Add docs/specs/bug-finder-agent.md, brainstorm-agent.md, review-cluster.md — closing the spec coverage gap
- Fix: all 5 lifecycle tool execute() now return JSON.stringify — the OpenCode plugin API requires Promise<string>, raw objects caused a silent crash at runtime - Add tools/lifecycle.js: 5 deterministic bookkeeping functions (projectState, markBlockDone, completePlan, registerSpec, checkArtifacts) - Add tests/lifecycle.test.js: 28 tests with node:test + node:assert/strict, zero deps, each test runs in an isolated tmpDir - Add npm test script (node --test tests/*.test.js) - Add docs/specs/lifecycle-tools.md and review-manager-mechanical-checks.md - Update agents/prompt.md, docs/index.md with harness/planning/gardener additions from previous session
- README.md: add Lifecycle Tools section documenting the 5 bookkeeping tools - AGENTS.md: update tests references, add lifecycle tools to enforcement table - CHANGELOG.md: add Fixed entry for lifecycle tools execute return type - orion-docs/: new technical documentation website (7 sections, React + Tailwind) with lifecycle tools, all 9 agents, 5-phase workflow detail - team-lead-workflow/: update agents list and flowchart for consistency
* 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)
- Add @opencode-ai/plugin as a real dependency (^1.3.17) instead of peer dep
— peer dep was not resolvable from Node's ESM resolution chain on fresh installs
- Update zero-deps CI check: allow @opencode-ai/plugin specifically, assert its presence
- Add engines field (node >=16.0.0) to document minimum Node version
- Add permissions: {} to checks.yml workflow for least-privilege
- Translate all French error/warning strings in lifecycle.js to English
- Tighten test assertions for not-found errors (file vs block vs status)
…ection - doc_dev_start/stop/status/logs — Vite dev server lifecycle management - doc_screenshot/navigate/get_html — headless Playwright browser tools - doc-inspector agent — orchestrates tools for visual doc inspection
- Rename brainstorm internal phases to Step 1/2/3 in WORKFLOW_DRAFT to avoid confusion with global Orion phases (Phase 1=PLAN, Phase 2=DELEGATE, etc.) - Replace simplistic Phase 0 (single Brief exist? node) with full entry logic: glob docs/briefs/, Briefs found? (0/1/N), Brief status? (draft/done), Continue or fresh start?, Revise or new project?, Load brief → Step 3, Step 1 direct/normal, Run brainstorm agent, Brief written → verbal suggestion - Add fast path dashed arrow from glob node to Phase 2 Select agent (bypass when scope is already clear) - Fix edge label visibility: inject CSS into SVG post-render to force dark background (#1e293b) and white text on all Mermaid edge labels - Add optional dashed arrow Phase 4 → Phase 5 (maintenance is post-delivery) - Rebuild bundle.html
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
2 participants
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
WORKFLOW_DRAFT.mdto avoid confusion with the global Orion phases (Phase 1=PLAN, Phase 2=DELEGATE, etc.)Brief exist?node) with the full entry logic from the DRAFT:glob docs/briefs/→Briefs found?(0/1/N branches) →Brief status?(draft/done) →Continue or fresh start?/Revise or new project?→Load brief → Step 3/Step 1 normal/Step 1 direct→Run brainstorm agent→Brief written → verbal suggestionglob docs/briefs/directly to Phase 2Select agent(bypass when scope is already clear)#1e293b) and white text on all Mermaid edge labelsbundle.htmlChanged Files
team-lead-workflow/WORKFLOW_DRAFT.mdteam-lead-workflow/src/App.tsxteam-lead-workflow/bundle.html