fix: triage bundle — agentsDir lookup, Codex legacy README, useBeads gate#59
Merged
fix: triage bundle — agentsDir lookup, Codex legacy README, useBeads gate#59
Conversation
Closes #50, #55. #55: hooks/detect-env.{sh,ps1} hardcoded .agents/setup-state.json even after PR #54 wired CLAUDE_PLUGIN_OPTION_AGENTSDIR into DEFAULT_ROOT_DIR. With agentsDir=specs the configured root was silently masked and the hook reported "(default)". Lookup now resolves ${DEFAULT_ROOT_DIR}/setup-state.json first and falls back to .agents/setup-state.json so users who switched agentsDir mid-project keep working. #50: README's legacy / repo-scoped Codex install block placed the marketplace.json at ~/.agents/plugins/marketplace.json with a "~/.codex/plugins/flow" path — Codex 0.125+ rejects any local marketplace path that doesn't start with "./". Restructure: place the marketplace manifest next to the cloned repo at ~/.codex/plugins/marketplace.json with path "./flow", which resolves relative to the manifest directory.
…53) Until now, only hooks/detect-env.{sh,ps1} consulted the useBeads userConfig toggle (3 references in the entire repo), while every flow command, agent, and TOML mirror shelled out to `bd` unconditionally. Toggling useBeads=false suppressed the SessionStart context block but every command still emitted "command not found" — the toggle was effectively a no-op. Centralize the rule: - skills/flow/references/discipline.md — new "Beads Mode Iron Law" section alongside TDD/Debugging/Verification, with a signal table mapping the three SessionStart hook outputs (Official / Missing / Disabled) to the required agent behavior. - agents/{executor,plan-generator,prd-orchestrator}.md — add the gate to each agent's IRON LAWS / ZERO-AMBIGUITY MANDATE block so spec generation, PRD orchestration, and task execution all degrade gracefully when bd is absent or disabled. - templates/opencode/agents/flow.md — equivalent rule in OpenCode's Critical Rules list. - commands/flow-{implement,status,archive,finish,task,prd,refine,review,revise}.md and their commands/flow/*.toml mirrors (archive, review, validate, refine, status, sync) — short preamble pointing to the canonical rule, so agents reading a single command file still see the gate even without the discipline reference loaded. Falls back to spec.md markers ([ ], [~], [x], [!], [-]) as the source of truth in degraded mode. Never halts for missing Beads.
Earlier commit converted the Beads-mode preamble to a plain paragraph to duck markdownlint's MD028. The correct fix is to keep the blockquote (it's semantically a callout, matching the existing 'Lifecycle skill' note style) and merge the two adjacent blockquotes into one continuous block separated by '>' — markdownlint's documented remedy for MD028. The blockquote callout reads as a callout in any rendered markdown and groups the two pre-flight notes (Beads gate + lifecycle skill) into a single visual block, which is what the structure already implies.
cofin
changed the title
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
Bundled fixes from the open-issue triage. Closes #50, #53, #55. (#37 closed separately as already-addressed; #48 deferred per maintainer preference.)
#55 —
agentsDir-aware setup-state lookuphooks/detect-env.{sh,ps1}hardcoded.agents/setup-state.jsoneven after #54 wiredCLAUDE_PLUGIN_OPTION_AGENTSDIRintoDEFAULT_ROOT_DIR. WithagentsDir=specsconfigured, the hook silently fell through to the "(default)" branch, masking the user's chosen root. Lookup now uses${DEFAULT_ROOT_DIR}/setup-state.jsonfirst, with.agents/setup-state.jsonas a backward-compat fallback for users who switchedagentsDirmid-project.#50 — Valid Codex 0.125+ legacy install path
README's legacy/manual Codex install block placed the marketplace manifest at
~/.agents/plugins/marketplace.jsonand used"path": "~/.codex/plugins/flow". Codex 0.125+ rejects any local marketplace path that isn't prefixed with./. Restructured: marketplace manifest goes next to the cloned repo at~/.codex/plugins/marketplace.jsonwith"path": "./flow", which resolves correctly relative to the manifest's directory.#53 — Gate every
bdinvocation onuseBeads/availabilityUntil now, only
hooks/detect-env.{sh,ps1}consulted theuseBeadsuserConfig (3 references in the entire repo); every flow command, agent, and TOML mirror shelled out tobdunconditionally. TogglinguseBeads=falsesuppressed the SessionStart context block but every command still emittedcommand not found— the toggle was effectively a no-op. Centralized the rule:skills/flow/references/discipline.md— newBeads Mode Iron Lawsection alongside TDD/Debugging/Verification, with a signal table mapping the three SessionStart hook outputs (Official / Missing / Disabled) to the required agent behavior.agents/{executor,plan-generator,prd-orchestrator}.md+templates/opencode/agents/flow.md— gate added to each agent's IRON LAWS / ZERO-AMBIGUITY MANDATE / Critical Rules block.commands/flow-{implement,status,archive,finish,task,prd,refine,review,revise}.md+commands/flow/{archive,review,validate,refine,status,sync}.tomlmirrors — short Beads-mode preamble pointing to the canonical rule, so an agent reading a single command file still sees the gate even without the discipline reference loaded. Markdown preambles are merged into the existing lifecycle-skill blockquote (one continuous callout, MD028-clean).Falls back to
spec.mdmarkers ([ ],[~],[x],[!],[-]) as the source of truth in degraded mode. Never halts for missing Beads.Test plan
make checkpasses (lint, skills, codex, version sync) — twice (initial and after the MD028 correction)hooks/detect-env.shsmoke-tested for all three lookup paths in/tmp/flow-test/:.agents/+.agents/setup-state.json→ reads correctlyagentsDir=specs+specs/setup-state.json→ reads correctly (the bug fix)agentsDir=specs+ no state file → "(default)" branch as expectedclaude plugin install flow@flow-marketplaceand confirm/doctorno longer flags either Codex oragentsDirissueuseBeads=falsemode: install plugin with toggle off, run/flow:statusand/flow:task— expect graceful degraded-mode output instead ofbd: command not found