Add cross-functional Archon workflow templates#1411
Open
RickRinewalt wants to merge 16 commits intocoleam00:devfrom
Open
Add cross-functional Archon workflow templates#1411RickRinewalt wants to merge 16 commits intocoleam00:devfrom
RickRinewalt wants to merge 16 commits intocoleam00:devfrom
Conversation
…be (coleam00#1359) The pre-flight binary smoke does a bare `bun build --compile` — it deliberately skips `scripts/build-binaries.sh` to stay fast. That means packages/paths/src/bundled-build.ts retains its dev defaults, including BUNDLED_IS_BINARY = false. version.ts branches on BUNDLED_IS_BINARY: when true it returns the embedded string; when false it calls getDevVersion(), which reads package.json at `SCRIPT_DIR/../../../../package.json`. Inside a compiled binary SCRIPT_DIR resolves under `$bunfs/root/`, the walk produces a CWD- relative path that doesn't exist, and the smoke aborts with "Failed to read version: package.json not found" — a false positive. Hit during the 0.3.8 release attempt: the real Pi lazy-load fix was working end-to-end; the smoke test was the only thing failing. Use --help instead. It exercises the same module-init graph (so it still catches the real failure modes the skill lists — Pi package.json init crash, Bun --bytecode bugs, CJS wrapper issues, circular imports under minify) but has no dev/binary branch, so no false positive. Also add a longer comment block explaining why --help is preferred, so this doesn't get "normalized" back to `version` by a future drive-by.
The brew path of /test-release runs `brew uninstall` in Phase 5 to leave the system in its pre-test state. For operators using the dual-homebrew pattern (renamed brew binary at `/opt/homebrew/bin/archon-stable` so it coexists with a `bun link` dev `archon`), that uninstall wipes the Cellar dir the `archon-stable` symlink points into → `archon-stable` becomes dangling → `brew cleanup` sweeps it away on the next brew op. Next time the operator wants stable, they have to manually re-run `brew-upgrade-archon`. Fix: make the skill aware of `archon-stable` and restore it transparently. - Phase 2 item 4: detect the `archon-stable` symlink before any brew op; export `ARCHON_STABLE_WAS_INSTALLED=yes` so Phase 5 knows to restore it. Only triggers for the brew path (curl-mac/curl-vps don't touch brew so they leave `archon-stable` alone). - Phase 5 brew path: after `brew uninstall + untap`, if the flag was set, re-tap + re-install + rename. Verifies the restored `archon-stable` reports a version and warns (non-fatal) if the rename target is missing. Documents the tradeoff: the restored version is "whatever the tap ships today", not necessarily the pre-test version — usually that's what the operator wants (the release they just tested becomes stable) but the back-version-QA case requires a manual `brew-upgrade-archon` after. - Phase 1 confirmation banner now mentions that `archon-stable` will be preserved so the operator isn't surprised by the reinstall during Phase 5. No changes to curl-mac/curl-vps paths. No changes to Phase 4 test suite.
… a compiled binary (coleam00#1360) v0.3.9 made Pi boot-safe: lazy-loading its imports meant `archon version` no longer crashed on `@mariozechner/pi-coding-agent/dist/config.js`'s module-init `readFileSync(getPackageJsonPath())`. That's what the `provider-lazy-load.test.ts` regression test guards. The fix was only half the problem though. When a Pi workflow actually runs, sendQuery() triggers the dynamic import — and Pi's config.js module-init fires then, hitting the exact same ENOENT on `dirname(process.execPath)/package.json`. Discovered by running `archon workflow run test-pi` against a locally-compiled 0.3.9 binary: [main] Failed: ENOENT: no such file or directory, open '/private/tmp/package.json' at readFileSync (unknown) at <anonymous> (/$bunfs/root/archon-providertest:184:7889) at init_config Boot-safe ≠ runtime-safe. The `/test-release` run for 0.3.9 passed because it only exercised `archon-assist` (Claude); Pi was never actually invoked on the released binary. Fix: before the dynamic `import('@mariozechner/pi-coding-agent')` in sendQuery, install a PI_PACKAGE_DIR shim. Pi's config.js checks `process.env.PI_PACKAGE_DIR` first in its `getPackageDir()` and short-circuits the `dirname(process.execPath)` walk. We write a minimal `{name, version, piConfig:{}}` stub to `tmpdir()/archon-pi-shim/package.json` (idempotent — existsSync check) and set the env var. Pi only reads `piConfig.name`, `piConfig.configDir`, and `version` from that file, all optional, so the stub surface is genuinely minimal. Localized to PiProvider: no global state, no mutation of any shared config, no upstream fork. Claude and Codex providers are unaffected (their SDKs don't have this class of module-init side effect). Verified end-to-end: built a compiled archon binary with this patch, ran `archon workflow run test-pi --no-worktree` (Pi workflow with model `anthropic/claude-haiku-4-5`), got a clean response. Before the patch, same binary crashed at `dag_node_started` with the ENOENT above. Regression test added: asserts `PI_PACKAGE_DIR` is set after sendQuery hits even its fast-fail "no model" path. Together with the existing `provider-lazy-load.test.ts` (boot-safe) this covers both halves.
… and Codex (coleam00#1361) Both binary resolvers previously stopped at env-var + explicit config and threw a "not found" error when neither was set. Users who followed the upstream-recommended install flow (Anthropic's `curl install.sh` for Claude, `npm install -g @openai/codex`) still had to manually set either `CLAUDE_BIN_PATH` / `CODEX_BIN_PATH` or the corresponding config field before any workflow could run. Add a tier-N autodetect step between the explicit config tier and the install-instructions throw. Purely additive: env and config still win when set (precedence covered by new tests). On autodetect miss, the same install-instructions error fires as before. Claude probe list (verified against docs.claude.com "Uninstall Claude Code → Native installation" section): - $HOME/.local/bin/claude (mac/linux native installer) - $USERPROFILE\.local\bin\claude.exe (Windows native installer) Codex probe list (verified against openai/codex README; npm global- install puts the binary at `{npm_prefix}/bin/<name>` on POSIX, `{npm_prefix}\<name>.cmd` on Windows): - $HOME/.npm-global/bin/codex (user-set `npm config set prefix`) - /opt/homebrew/bin/codex (mac arm64 with homebrew-node) - /usr/local/bin/codex (mac intel / linux system node) - %APPDATA%\npm\codex.cmd (Windows npm global default) - $HOME\.npm-global\codex.cmd (Windows user-set prefix) Not probed (explicit override still required): - Custom npm prefixes — `npm root -g` would need a subprocess per resolve, too much surface for a probe helper - `brew install --cask codex` — cask layout isn't a PATH binary - Manual GitHub Releases extracts — placement is user-determined - `~/.bun/bin/codex` — not documented in openai/codex README Pi provider intentionally has no equivalent change: the Pi SDK is bundled into the archon binary (no subprocess), so there's no "binary" to resolve. Pi auth lives at `~/.pi/agent/auth.json` which the SDK already finds by default, and the PR A shim (`PI_PACKAGE_DIR`) handles the package-dir case via Pi's own documented escape hatch. E2E verified: removed both config entries from ~/.archon/config.yaml, rebuilt compiled binary, ran `archon workflow run archon-assist` and a Codex workflow. Logs showed `source: 'autodetect'` for both, responses returned cleanly.
…ry autodetect test The native-installer autodetect test computed its expected path from process.env.HOME, but the implementation uses node:os homedir(). On Windows, HOME is typically unset (Windows uses USERPROFILE), so the test fell back to '/Users/test' while the resolver returned the real home dir — making the spy's path-equality check fail and breaking CI on windows-latest. Mirror the implementation by importing homedir() from node:os and joining with node:path so the expected path matches the actual platform-resolved home and separator. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…ver (coleam00#1365) Reported in coleam00#1365: a user running `archon serve` with DISCORD_BOT_TOKEN set but the "Message Content Intent" toggle disabled in the Discord Developer Portal saw the entire server crash with `Used disallowed intents`. Discord rejects the gateway connection (close code 4014) when a privileged intent is requested without being enabled, and the unguarded `await discord.start()` propagated the error all the way up, taking the web UI down with it. Wrap discord.start() in try/catch — log the failure with an actionable hint (special-cased for the disallowed-intent error) and continue running. Other adapters and the web UI come up regardless. The shutdown handler already uses optional chaining (`discord?.stop()`) so nulling discord after a failed start is safe. Other adapters (Telegram, Slack, GitHub, Gitea, GitLab) have the same unguarded-start pattern but are out of scope for this fix — addressing them is tracked separately. Also expanded the Discord setup docs with a caution callout that names the exact error string and the new log event so users can grep for both. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
…0#1362) * docs(script-nodes): add dedicated guide and teach the archon skill how to write them Script nodes (script:) have been a first-class DAG node type since v0.3.3 but were documented only as one-liners in CLAUDE.md and a CI smoke test. Claude Code reading the archon skill would see "Four Node Types: command, prompt, bash, loop" and reach for bash+node/python one-liners instead of a proper script node — losing bun's --no-env-file isolation, uv's --with dependency pins, and the .archon/scripts/ reuse story. - New packages/docs-web/src/content/docs/guides/script-nodes.md mirroring the structure of loop-nodes.md / approval-nodes.md: schema, inline vs named dispatch, runtime/deps semantics, scripts directory precedence (repo > home), extension-runtime mapping, env isolation, stdout/stderr contract, patterns, and the explicit list of ignored AI fields. - guides/authoring-workflows.md and guides/index.md updated so the new guide is discoverable from both the node-types table and the guides landing page. - reference/variables.md calls out the no-shell-quote difference between bash: and script: substitution — a subtle correctness trap when adapting a bash pattern into a script node. - Sidebar order bumped +1 on hooks/mcp-servers/skills/global-workflows/ remotion-workflow to slot script-nodes at order 5 next to the other node-type guides. - .claude/skills/archon/SKILL.md: replaces stale "Four Node Types" (which also silently omitted approval and cancel) with the accurate seven, with a script-node code block showing both inline and named patterns. - references/workflow-dag.md: full Script Node section covering dispatch, resolution, deps, stdout contract, and the list of AI-only fields that are ignored; validation-rules list updated. - references/dag-advanced.md and references/variables.md: retry-support line corrected; no-shell-quote note added. - examples/dag-workflow.yaml: added an extract-labels TypeScript script node and updated the header comment. * fix(docs): review follow-ups for script-node guide - skills example: extract-labels was reading process.env.ISSUE_JSON which is never set; use String.raw`$fetch-issue.output` so the upstream bash node's JSON is actually consumed - guides/script-nodes.md + skills/workflow-dag.md: idle_timeout is accepted but ignored on script (and bash) nodes — executeScriptNode only reads node.timeout. Clarify that script/bash use `timeout`, not idle_timeout - archon-workflow-builder.yaml: prompt enumerated only bash/prompt/command/loop, so the AI builder could never propose script or approval nodes. Add both (plus examples + rule about script output not being shell-quoted) and regenerate bundled defaults - book/dag-workflows.md + book/quick-reference.md + adapters/web.md: fill in the node-type references that were missing script, approval, and cancel. adapters/web.md also overclaimed "loop" in the palette — NodePalette.tsx only drags command/prompt/bash, so note that the other kinds are YAML-only
…nv gaps, add good-practices + troubleshooting (coleam00#1363) * fix(skill/when): document the full `when:` operator set and compound expressions The skill reference previously stated "operators: ==, != only" which is materially wrong — the condition evaluator supports ==, !=, <, >, <=, >= plus && / || compound expressions with && binding tighter than ||, plus dot-notation JSON field access. An agent authoring a workflow from the skill would think half the operators don't exist. Replaces the single-sentence section with a structured reference covering: - All six comparison operators (string and numeric modes) - Compound expressions with precedence rules and short-circuit eval - JSON dot notation semantics and failure modes - The fail-closed rules in full (invalid expression, non-numeric side, missing field, skipped upstream) Grounded in packages/workflows/src/condition-evaluator.ts. * feat(skill): document Approval and Cancel node types Approval and cancel nodes are first-class DAG node types (approval since the workflow lifecycle work in coleam00#871, cancel as a guarded-exit primitive) but the skill never described either one. An agent reading the skill and asked to "add a review gate before implementation" or "stop the workflow if the input is unsafe" would fall back to bash + exit 1, losing the proper semantics (cancelled vs. failed, on_reject AI rework, web UI auto-resume). Approval node coverage (references/workflow-dag.md, SKILL.md): - Full configuration block with message, capture_response, on_reject - The interactive: true workflow-level requirement for web UI delivery - Approve/reject commands across all platforms (CLI, slash, natural language) and the capture_response → $node-id.output flow - Ignored-fields list + the on_reject.prompt AI sub-node exception Cancel node coverage (references/workflow-dag.md, SKILL.md): - Single-field schema (cancel: "<reason>") - Lifecycle: cancelled (not failed); in-flight parallel nodes stopped; no DAG auto-resume path - The "cancel: vs bash-exit-1" decision rule (expected precondition miss vs. check itself failing) - Two canonical patterns — upstream-classification gate, pre-expensive-step gate Validation-rules list updated to enumerate approval/cancel constraints (message non-empty, on_reject.max_attempts range 1-10, cancel reason non-empty), plus a forward note that script: joins the mutually-exclusive set once PR coleam00#1362 lands. Placement in both files is after the Loop section and before the validation section, so this commit stays additive with respect to PR coleam00#1362's Script node insertion between Bash and Loop — rebase is clean. * feat(skill): document workflow-level fields beyond name/provider/model The skill's Schema section previously showed only name, description, provider, and model at the workflow level — which is most of a stub. Agents asked to "use the 1M-context Claude beta" or "run this under a network sandbox" or "add a fallback model in case Opus rate-limits" had no way to discover that any of these fields existed at the workflow level. Adds a comprehensive Workflow-Level Fields section covering: - Core: name, description, provider, model, interactive (with explicit callout that interactive: true is REQUIRED for approval/loop gates on web UI — a common footgun) - Isolation: worktree.enabled for pin-on/pin-off (the only worktree field at workflow level; baseBranch/copyFiles/path/initSubmodules are config.yaml only, so a cross-reference points there) - Claude SDK advanced: effort, thinking, fallbackModel, betas, sandbox, with explicit per-node-only exceptions (maxBudgetUsd, systemPrompt) - Codex-specific: modelReasoningEffort (with note that it's NOT the same as Claude's effort — this has confused users), webSearchMode, additionalDirectories - A complete worked example combining sandbox + approval + interactive All fields cross-referenced against packages/workflows/src/schemas/workflow.ts and packages/workflows/src/schemas/dag-node.ts. * feat(skill/loop): document interactive loops and gate_message Interactive loop nodes pause between iterations for human feedback via /workflow approve — used by archon-piv-loop and archon-interactive-prd. The skill's Loop Nodes section previously omitted both interactive: true and gate_message entirely, so an agent writing a guided-refinement workflow wouldn't know the feature exists or that gate_message is required at parse time. Adds: - interactive and gate_message rows to the config table (marking gate_message as required when interactive: true — enforced by the loader's superRefine) - A dedicated "Interactive Loops" subsection explaining the 6-step iterate-pause-approve-resume flow - Explicit call-out that $LOOP_USER_INPUT populates ONLY on the first iteration of a resumed session — easy to miss and a common surprise - Workflow-level interactive: true requirement for web UI delivery (loader warning otherwise) so the full-flow example is complete - Note that until_bash substitution DOES shell-quote $nodeId.output (unlike script bodies) — called out since the audit surfaced this inconsistency * fix(skill/cli): complete the CLI command reference with missing lifecycle commands The CLI reference previously documented only list, run, cleanup, validate, complete, version, setup, and chat — missing nearly every workflow lifecycle command an agent needs to operate a paused, failed, or stuck run. The interactive-workflows reference assumed these commands existed without actually documenting them. Adds full documentation for: - archon workflow status — show running workflow(s) - archon workflow approve <run-id> [comment] — resume approval gate (also populates $LOOP_USER_INPUT on interactive loops and the gate node's output when capture_response: true) - archon workflow reject <run-id> [reason] — reject gate; cancels or triggers on_reject rework depending on node config - archon workflow cancel <run-id> — terminate running/paused with in-flight subprocess kill - archon workflow abandon <run-id> — mark stuck row cancelled without subprocess kill (for orphan-cleanup after server crashes — matches the coleam00#1216 precedent) - archon workflow resume <run-id> [message] — force-resume specific run (auto-resume is default; this is for explicit override) - archon workflow cleanup [days] — disk hygiene for old terminal runs (with explicit callout that it does NOT transition 'running' rows, a common confusion) - archon workflow event emit — used inside loop prompts for state signalling; documented so agents don't invent their own mechanism - archon continue <branch> [flags] [msg] — iterative-session entry point with --workflow and --no-context flags Also: - Adds --allow-env-keys flag to the `workflow run` flag table with audit-log context and the env-leak-gate remediation use case - Adds an "Auto-resume without --resume" note disambiguating when --resume is needed vs. when auto-resume handles it - Adds --include-closed flag to `isolation cleanup`, which was previously missing; converts the flag list to a structured table - Explains the cancel/abandon distinction (live subprocess vs. orphan) All grounded in packages/cli/src/commands/workflow.ts, continue.ts, and isolation.ts. * feat(skill/repo-init): add scripts/ and state/, three-path env model, per-project env injection The repo-init reference was missing two first-class .archon/ directories (scripts/ since v0.3.3, state/ since the workflow-state feature) and had nothing to say about env — the #1 thing a user hits on first-run when their repo has a .env file with API keys. Directory tree updates: - Adds .archon/scripts/ with the extension->runtime rule (.ts/.js -> bun, .py -> uv) so agents know where to put named scripts referenced by script: nodes. - Adds .archon/state/ with explicit "always gitignore" callout — these are runtime artifacts, not source. Previously undocumented in the skill. - Adds .archon/.env (repo-scoped Archon env) and distinguishes it from the target repo's top-level .env. - Adds a "What each directory is for" list so the structure isn't just a tree with no narrative. .gitignore guidance: - state/ and .env added as must-gitignore (state/ matches CLAUDE.md and reference/archon-directories.md — skill was lagging). - mcp/ demoted to conditional — gitignore only if you hardcode secrets. New "Three-Path Env Model" section: - ~/.archon/.env (trusted, user), <cwd>/.archon/.env (trusted, repo), <cwd>/.env (UNTRUSTED, target project — stripped from subprocess env). - Precedence (override: true across archon-owned paths) and the observable [archon] loaded N keys / stripped K keys log lines so operators can verify what actually happened. - Decision tree for where to put API keys vs. target-project env vs. things Archon shouldn't touch. - Links to archon setup --scope home|project with --force for writing to the right file with timestamped backups. New "Per-Project Env Injection" section: - Documents both managed surfaces: .archon/config.yaml env: block (git-committed, $REF expansion) and Web UI Settings → Projects → Env Vars (DB-stored, never returned over API). - Names every execution surface that receives the injected vars: Claude/Codex/Pi subprocess, bash: nodes, script: nodes, and direct codebase-scoped chat. - Documents the env-leak gate with all 5 remediation paths so an agent hitting "Cannot register: env has sensitive keys" knows the options. Grounded in CHANGELOG v0.3.7 (three-path env + setup flags), v0.3.0 (env-leak gate), and reference/security.md on the docs site. * fix(skill/authoring-commands): correct override paths and add home-scoped commands The file-location and discovery sections described an override layout that does not match the actual resolver. It showed: .archon/commands/defaults/archon-assist.md # Overrides the bundled and claimed `.archon/commands/defaults/` was where repo-level overrides lived. In fact the resolver (executor-shared.ts:152-200 + command- validation.ts) walks `.archon/commands/` 1 level deep and uses basename matching — putting `archon-assist.md` at the top of `.archon/commands/` is the canonical way to override the bundled version. The `defaults/` subfolder is a Archon-internal convention for shipping bundled defaults, not a user-facing override pattern. Also, home-scoped commands (`~/.archon/commands/`, shipped in v0.3.7) were completely absent — agents authoring personal helpers wouldn't know they could live at the user level and be shared across every repo. Changes: - File Location section now shows all three discovery scopes (repo, home, bundled) with precedence ordering and 1-level subfolder rules - Duplicate-basename rule documented as a user error surface - Discovery and Priority section rewritten with accurate 3-step lookup order — no more references to the nonexistent defaults/ override path - Adds the Web UI "Global (~/.archon/commands/)" palette label note so users authoring helpers for the builder know what to expect No code changes — this is a pure fix of stale/incorrect skill reference material. * feat(skill): add workflow good-practices and troubleshooting reference pages Closes two gaps from the audit. The skill previously had zero guidance on designing multi-node workflows (what to avoid, what to reach for first, how to structure artifact chains) and zero guidance on where to look when things go wrong (log paths, env-leak gate remediations, orphan-row cleanup, resume semantics). New references/good-practices.md (9 Good Practices + 7 Anti-Patterns): - Use deterministic nodes (bash:/script:) for deterministic work, AI for reasoning — the single biggest quality lever - output_format required whenever downstream when: reads a field — the most common source of "workflow silently routes wrong" - trigger_rule: none_failed_min_one_success after conditional branches — the classic bug where all_success fails because a skipped when:-gated branch doesn't count as a success - context: fresh requires artifacts for state passing — commands must explicitly "read $ARTIFACTS_DIR/..." when downstream of fresh - Cheap models (haiku) for glue, strong for substance - Workflow descriptions as routing affordances - Validate (archon validate workflows) + smoke-run before shipping - Artifact-chain-first design - worktree.enabled: true for code-changing workflows (reversibility) - Anti-patterns with before/after YAML examples for each (AI-for-tests, free-form when: matching, context: fresh without artifacts, long flat AI-node layers, secrets in YAML, retry on loop nodes, tiny max_iterations, missing workflow-level interactive:, tool-restricted MCP nodes) New references/troubleshooting.md: - Log location (~/.archon/workspaces/<owner>/<repo>/logs/<run-id>.jsonl) with jq recipes for common queries (last assistant message, failed events, full stream) - Artifact location for cross-node handoff debugging - 9 Common Failure Modes, each with root cause + concrete fix: - $BASE_BRANCH unresolvable - Env-leak gate (5 remediations) - Claude/Codex binary not found (compiled-binary-only) - "running" forever (AI working / orphan / idle_timeout) - Mid-workflow failure and auto-resume semantics - Approval gate missing on web UI (workflow-level interactive:) - MCP plugin connection noise (filtered by design) - Empty $nodeId.output / field access (4 causes) - Diagnostic command cheat sheet (list, status, isolation list, validate, tail-log, --verbose, LOG_LEVEL=debug) - Escalation protocol (version + validate + log tail + CHANGELOG + issue) SKILL.md routing table now dispatches "Workflow good practices / anti-patterns" and "Troubleshoot a failing / stuck workflow" to the new references so an agent can find them without having to know they exist. * docs(book): update node-types coverage from four to all seven The book is the curated first-contact reading path (landing page → "Get Started" → /book/). Both dag-workflows.md and quick-reference.md were stuck on "four node types" — missing script, approval, and cancel. A user reading the book as their first introduction would form an incomplete mental model, then find three more node types in the reference section later with no explanation of when they arrived. book/dag-workflows.md: - "four node types" → "seven node types. Exactly one mode field is required per node" - Table now lists Command, Prompt, Bash, Script, Loop, Approval, Cancel with one-line "when to use" for each, and cross-links to the dedicated guide pages for Script / Loop / Approval - New sections below the table for Script (inline + named examples with runtime and deps), Approval (with the interactive: true workflow-level note that's easy to miss), and Cancel (guarded-exit pattern) — keeping the existing narrative shape for Bash and Loop book/quick-reference.md: - Node Options table now includes script, approval, cancel rows - agents row added (inline sub-agents, Claude-only) - New "Script-specific fields" and "Approval-specific fields" subsections so the cheat-sheet is actually complete rather than pointing users elsewhere for the required constraints - Retry row callout that loop nodes hard-error on retry — previously omitted - bash timeout note widened to cover script timeout (same semantics) Both files are docs-web content; the CI build on the docs-script-nodes PR (coleam00#1362) previously validated the Starlight build path with a similar table addition, so this should render clean. * fix(skill/cli): remove nonexistent \`archon workflow cancel\`, fix workflow status jq recipe Two accuracy issues from the PR code-reviewer (comment 4311243858). C1: \`archon workflow cancel <run-id>\` does NOT exist as a CLI subcommand. The switch at packages/cli/src/cli.ts:318-485 dispatches on list / run / status / resume / abandon / approve / reject / cleanup / event — running \`archon workflow cancel\` hits the default case and exits with "Unknown workflow subcommand: cancel" (cli.ts:478-484). Active cancellation is only available via: - /workflow cancel <run-id> chat slash command (all platforms) - Cancel button on the Web UI dashboard - POST /api/workflows/runs/{runId}/cancel REST endpoint cli-commands.md: removed the \`### archon workflow cancel <run-id>\` subsection; kept the \`abandon\` subsection but made it explicit that abandon does NOT kill a subprocess. Added a call-out box at the bottom of the abandon section explaining where to go for actual cancellation. troubleshooting.md "running forever" section: split the original cancel-vs-abandon advice into three bullets — Web UI / CLI abandon (for orphans, no subprocess kill) / chat \`/workflow cancel\` (for live runs that need interruption). Added an explicit "there is no archon workflow cancel CLI subcommand" parenthetical since the wrong command was being suggested in flow. I1: the \`archon workflow list --json\` diagnostic used an incorrect jq filter. workflow list's --json output (workflow.ts:185-219) has shape { workflows: [{ name, description, provider?, model?, ... }], errors: [...] } with no \`runs\` field — \`jq '.workflows[] | select(.runs)'\` returns empty unconditionally. Replaced with \`archon workflow status --json | jq '.runs[]'\`, which matches the actual shape of workflowStatusCommand at workflow.ts:852+ ({ runs: WorkflowRun[] }). Also tightened the narration to distinguish JSON from human-readable status output. No change to the commit history in this PR — these are follow-up fixes to claims I introduced in earlier commits of this branch (f10b989 for C1, 66d2b86 for I1). * fix(skill): remove env-leak gate references (feature was removed in provider extraction) C2 from the PR code-reviewer (comment 4311243858). The pre-spawn env-leak gate was removed from the codebase during the provider-extraction refactor — see TODO(coleam00#1135) at packages/providers/src/claude/provider.ts:908. Zero hits for --allow-env-keys / allowEnvKeys / allow_env_keys / allow_target_repo_keys across packages/. The CLI's parseArgs (cli.ts:182-208) has no --allow-env-keys option, and because parseArgs uses strict: false, an unknown --allow-env-keys would be silently ignored rather than error. What remains accurate and is NOT touched: - Three-Path Env Model section (user/repo archon-owned envs are loaded; target repo <cwd>/.env keys are stripped from process.env at boot) still correctly describes current behavior, grounded in packages/paths/src/strip-cwd-env.ts + env-integration.test.ts - Per-Project Env Injection section (Option 1: .archon/config.yaml env: block; Option 2: Web UI Settings → Projects → Env Vars) is unchanged — both remain the sanctioned way to get env vars into subprocesses Removed claims (all three files): - cli-commands.md: --allow-env-keys flag row in the workflow run flags table - repo-init.md: the "Env-leak gate" subsection at the end of Per-Project Env Injection listing 5 remediations (all of which reference UI/CLI/ config surfaces that don't exist). Replaced with a succinct callout that explains the actual current behavior — target repo .env keys are stripped, workflows that need those values should use managed injection — so the reader still gets the "where to put my env vars" answer - troubleshooting.md: the "Cannot register: codebase has sensitive env keys" section (error message that can no longer be emitted) If the env-leak gate is ever resurrected per TODO(coleam00#1135), the docs can be re-added then. The CHANGELOG v0.3.0 entry describing the gate is a historical record of past behavior and does not need to be rewritten. * fix(skill/troubleshooting): correct JSONL event type names and field name C3 from the PR code-reviewer (comment 4311243858). The troubleshooting reference's event-types table used _started / _completed / _failed suffixes, but packages/workflows/src/logger.ts:19-30 shows the actual WorkflowEvent.type enum is: workflow_start | workflow_complete | workflow_error | assistant | tool | validation | node_start | node_complete | node_skipped | node_error The second jq recipe also queried `.event` but the discriminator is `.type`. Fixes: - Event table: renamed columns (_started → _start, _completed → _complete, _failed → _error). Explicitly called out the field name as `type` so the reader knows what jq selector to use - Replaced the "tool_use / tool_result" row with a single `tool` row and listed its actual payload fields (tool_name, tool_input, duration_ms, tokens) — tool_use/tool_result are SDK message kinds that appear within the AI stream, not top-level log event types - Added a `validation` row (was missing; it's emitted by workflow-level validation calls with `check` and `result` fields) - Removed `retry_attempt` row — this event type is not emitted to the JSONL file. Retry bookkeeping goes through pino logs, not the workflow log file - Added an explicit callout that loop_iteration_started / loop_iteration_completed (and other emitter-only events) go through the workflow event emitter + DB workflow_events table, NOT the JSONL file. Pointed readers to the DB or Web UI for loop-level detail. This distinguishes the two parallel event systems — easy to conflate (store.ts:11-17 uses _started/_completed/_failed for the DB side, logger.ts uses _start/_complete/_error for JSONL) - Fixed the "all failed events" jq recipe: .event → .type and _failed → _error - Minor cleanup: the inline "tool_use events" mention in the "running forever" section said the wrong event name — updated to "tool or assistant events in the tail" Grounded in packages/workflows/src/logger.ts (canonical JSONL event shape) and packages/workflows/src/store.ts (the parallel DB event naming, which the reviewer correctly flagged as different and worth keeping distinct). * fix(skill): two stragglers from the code-reviewer audit Cleanup of two references that slipped through the earlier C1 and C3 fixes: - references/troubleshooting.md:126: \`node_failed\` → \`node_error\` (the "Node output is empty" diagnostics section references the JSONL log, which uses the logger.ts enum — not the DB workflow_events table which does use \`node_failed\`). The C3 fix corrected the event table and one jq recipe but missed this inline mention. - references/interactive-workflows.md:106: removed \`archon workflow cancel <run-id>\` (nonexistent CLI subcommand) from the troubleshooting bullet. This was pre-existing before the hardening PR but fell within the C1 remediation scope. Replaced with the correct triage: reject (approval gate only) vs abandon (orphan cleanup, no subprocess kill) vs chat /workflow cancel (actual subprocess termination). Grounded in the same sources as the earlier C1/C3 commits: packages/cli/src/cli.ts:318-485 (no cancel case) and packages/workflows/src/logger.ts:19-30 (JSONL type enum). * feat(skill): point to archon.diy as the canonical docs source The skill had no reference to archon.diy (the live docs site built from packages/docs-web/). Several reference files said "see the docs site" without naming the URL, leaving the agent to guess or grep the repo for the hostname. An agent with the skill loaded should know that when the distilled reference pages don't cover a case, the full canonical docs are one WebFetch away. SKILL.md: new "Richer Context: archon.diy" section between Routing and Running Workflows. Covers: - When to reach for the live docs (longer examples, tutorial framing, features the skill only mentions in passing, "where's that documented?" user questions) - URL map — 13 starting points covering getting-started, book (tutorial series), guides/ (authoring + per-node-type + per-node-feature), reference/ (variables, CLI, security, architecture, configuration, troubleshooting), adapters/, deployment/ - Precedence: skill refs first (context-cheap, tuned for agents), docs site as escalation. Prevents agents defaulting to WebFetch when a local skill ref already covers the answer Also upgrades the 5 existing generic "docs site" mentions across reference files to concrete archon.diy URLs with anchor fragments where helpful: - good-practices.md: Inline sub-agents pattern → archon.diy/guides/ authoring-workflows/#inline-sub-agents - troubleshooting.md: "Install page on the docs site" → archon.diy/ getting-started/installation/ - workflow-dag.md: "Workflow Description Best Practices" → anchor link; sandbox schema reference → archon.diy/guides/authoring-workflows/ #claude-sdk-advanced-options - repo-init.md: Security Model reference → archon.diy/reference/ security/#target-repo-env-isolation (deep-link into the section that covers the <cwd>/.env strip behavior) URL source of truth: astro.config.mjs:5 (site: 'https://archon.diy'). URL structure mirrors packages/docs-web/src/content/docs/<section>/ <page>.md — verified by the 62 pages the docs build produces.
…#1395) Anthropic's Opus 4.7 landed 2026-04-16; on the Anthropic API, opus / opus[1m] now resolve to 4.7 with a 1M context window at standard pricing. Using the alias instead of the hard-pinned claude-opus-4-6[1m] lets bundled default workflows auto-track the recommended Opus version. No explicit effort is set, so nodes inherit the per-model default (xhigh on 4.7, high on 4.6).
…m00#1398) * fix(workflow): migrate piv-loop plan handoff to $ARTIFACTS_DIR (coleam00#1380) The create-plan node used a relative path (.claude/archon/plans/{slug}.plan.md) that the AI agent would sometimes write to a different location, breaking all downstream nodes that glob for the plan file. Migrated all plan/progress file references to $ARTIFACTS_DIR/plan.md and $ARTIFACTS_DIR/progress.txt, matching the pattern used by archon-fix-github-issue and other workflows. Changes: - Replace slug-based plan path with $ARTIFACTS_DIR/plan.md in create-plan node - Replace ls -t glob discovery with direct $ARTIFACTS_DIR/plan.md reads in refine-plan, code-review, and fix-feedback nodes - Replace empty-string guard with file-existence check in implement-setup bash - Migrate progress.txt references in implement loop to $ARTIFACTS_DIR/ - Add explicit plan/progress paths in finalize node - Regenerated bundled-defaults.generated.ts Fixes coleam00#1380 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * fix(workflow): address review findings in archon-piv-loop - Rename 'Step 2: Write the Plan' to 'Step 2: Plan File Location' to eliminate the duplicate heading that collided with Step 3's identical title in the create-plan node - Guard implement-setup against a 0-task plan file: exit 1 with a clear error when no '### Task N:' sections are found, preventing a silent no-op implement loop - Remove 2>/dev/null from code-review commit so pre-commit hook failures and other stderr are visible to the agent instead of silently swallowed - Replace '|| true' on git push in finalize with an explicit WARNING echo so push failures (auth, upstream conflict, no remote) surface to the agent rather than being silently ignored - Regenerate bundled-defaults.generated.ts Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> * chore(workflows): regenerate bundled defaults to match opus[1m] alias The bundle was stale relative to the YAML sources after coleam00#1395 merged — check:bundled was failing CI. Regenerated; no YAML edits. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…cutor (coleam00#1403) PIV Task 1: Adds three new tests in a dedicated describe block 'executeDagWorkflow -- final status derivation' covering the anyFailed branch (dag-executor.ts ~line 2956) that previously had no direct test: - one success + one independent failure calls failWorkflowRun (not completeWorkflowRun) - multiple successes + one failure calls failWorkflowRun (not completeWorkflowRun) - trigger_rule: none_failed skips dependent node but anyFailed still marks run failed Fixes coleam00#1381.
New reference for the archon skill: a single-glance lookup of which parameter works on which node type, an intent-based "how do I..." table, a consolidated silent-failure catalog, and an inline agents: section (previously only referenced via archon.diy). Purpose is complementary, not duplicative: - workflow-dag.md remains the authoring guide - dag-advanced.md remains the hooks/MCP/skills/retry deep-dive - good-practices.md remains the patterns and anti-patterns - parameter-matrix.md is the grep-this-first lookup when you know the outcome you want but not which field gets you there Also registers the new reference in SKILL.md routing table.
📝 WalkthroughWalkthroughAdds ~30 new Archon command templates, 15+ workflow definitions, GitHub issue/PR templates, and cross-functional docs to standardize intake-to-delivery flows across Product, Design, Development, Security, QA, Docs, DevOps, and Services, including artifact templates and interactive approval gates. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant WorkflowEngine as Workflow Engine
participant CommandRunner as Command
participant ArtifactStore as Artifacts
participant Approver
User->>WorkflowEngine: start product-intake-to-prd (input/request)
WorkflowEngine->>CommandRunner: run product-intake-research (fresh context)
CommandRunner->>ArtifactStore: write `product/requirements.md`
WorkflowEngine->>Approver: request foundation-gate approval (capture response)
Approver-->>WorkflowEngine: approval response
WorkflowEngine->>CommandRunner: run product-prd-generate (uses requirements)
CommandRunner->>ArtifactStore: write `product/prd.md`
WorkflowEngine->>Approver: request product-approval (capture response)
Approver-->>WorkflowEngine: final approval
WorkflowEngine->>ArtifactStore: write `product/decision-log.md`
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 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 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 |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
🧹 Nitpick comments (7)
.archon/commands/docs/docs-release-notes.md (1)
18-20: Add explicit redaction guidance for security-derived content.Because this step reads security artifacts, add a clear rule to exclude sensitive internals (tokens, internal endpoints, exploit details) from user-facing notes.
Proposed wording
1. Read PR summaries, docs impact, QA, security, and services artifacts. 2. Separate user-facing changes from internal implementation details. +3. Redact sensitive details (secrets, internal-only endpoints, exploit mechanics, private incident data). -3. Write `$ARTIFACTS_DIR/docs/release-notes.md`. +4. Write `$ARTIFACTS_DIR/docs/release-notes.md`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.archon/commands/docs/docs-release-notes.md around lines 18 - 20, Update the release-notes step in docs-release-notes.md to include an explicit redaction rule for security-derived artifacts: when reading security artifacts (tokens, internal endpoints, exploit details, stack traces, credentials), redact or omit any sensitive internals and only surface high-level impact and mitigations in the user-facing release notes written to $ARTIFACTS_DIR/docs/release-notes.md; reference this rule in the steps that read security artifacts so the authoring workflow for writing release-notes.md enforces exclusion of secrets and internal-only details..github/pull_request_template.md (1)
106-109: Add a dedicated field forsecurity-risk-gateresult link/status.You require running/linking the gate, but there’s no explicit placeholder to capture the actual artifact URL/path and final verdict. A fixed field will improve review/audit consistency.
Proposed template addition
- If any `Yes`, describe risk and mitigation: - If any `Yes`, run or link `security-risk-gate`: +- `security-risk-gate` result link/artifact: +- `security-risk-gate` final verdict:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.github/pull_request_template.md around lines 106 - 109, Add a dedicated placeholder for the security gate artifact and verdict next to the existing "security-risk-gate" prompt: add two explicit fields such as "security-risk-gate-link: (URL to artifact)" and "security-risk-gate-verdict: (Pass/Fail/Not applicable)" so reviewers can record the gate result and link; update the block currently containing "If any `Yes`, run or link `security-risk-gate`" to require those fields and keep the existing risk/mitigation lines for consistency..archon/commands/security/security-dependency-review.md (1)
16-21: Add an explicit “no dependency changes” outcome.The process/output should state what to write when manifests/lockfiles/dependency layers are unchanged (e.g.,
Verdict: not applicable). This prevents forced or speculative risk findings when this command is invoked broadly.Proposed template tweak
## Process 1. Inspect package manifests, lockfiles, Dockerfiles, CI, install scripts, and release scripts. 2. Identify new packages, version changes, transitive risk, install-time scripts, and runtime permissions. +3. If no dependency or supply-chain-relevant changes are found, record "No relevant changes detected" and set verdict to "not applicable". -3. Write `$ARTIFACTS_DIR/security/dependency-review.md`. +4. Write `$ARTIFACTS_DIR/security/dependency-review.md`. ## Output -Return the verdict and artifact path. +Return the verdict (`clear` / `clear-with-follow-up` / `blocked` / `not-applicable`) and artifact path.Also applies to: 38-40
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.archon/commands/security/security-dependency-review.md around lines 16 - 21, Add an explicit "no dependency changes" outcome to the dependency review output: when inspecting manifests/lockfiles/Dockerfiles/install scripts yields no changes, write a clear line such as "Verdict: not applicable" into the generated artifact (the file referenced by Write $ARTIFACTS_DIR/security/dependency-review.md) and update the template/logic that produces lines 38-40 to emit this default verdict to avoid speculative findings..archon/commands/docs/docs-impact.md (1)
36-38: Possible duplication withdocs-release-notescommand.This artifact carries a
User-Facing Release Notessection, but the docs pipeline also runs a dedicateddocs-release-notescommand later. Consider whether this section should be (a) just a summary/pointer used bydocs-release-notesas input, or (b) renamed (e.g., "Release Notes Triggers" / "Customer-Visible Changes") to avoid two artifacts both claiming to be the source of truth for release notes copy.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.archon/commands/docs/docs-impact.md around lines 36 - 38, The "User-Facing Release Notes" section in docs-impact.md conflicts with the separate docs-release-notes command; update the artifact so it no longer duplicates the canonical release notes by either (a) turning the "User-Facing Release Notes" block into a short pointer/summary that explicitly references the docs-release-notes command as the source of truth, or (b) renaming the section to something unambiguous like "Release Notes Triggers" or "Customer-Visible Changes" and keeping only trigger/impact guidance. Locate the heading "User-Facing Release Notes" (and adjacent "Internal Enablement Notes") and modify its content and title accordingly so consumers know this file is not the authoritative release-notes copy.docs/archon/workflows/cross-functional-rollout.md (1)
1-156: LGTM — comprehensive rollout guide.The pilot workflow table names align with the workflow
name:fields (product-intake-to-prd,design-brief-to-handoff,security-risk-gate, etc.), and the security gate triggers cleanly mirror theclassify-securityprompt in.archon/workflows/security/security-risk-gate.yaml. Validation steps and end-to-end chain are useful for piloting.Minor nit (line 111): "Medium or high risk changes" reads better as "Medium- or high-risk changes" per LanguageTool. Non-blocking.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/archon/workflows/cross-functional-rollout.md` around lines 1 - 156, Replace the phrasing "Medium or high risk changes require security approval or documented risk acceptance before merge or release." with "Medium- or high-risk changes require security approval or documented risk acceptance before merge or release." in the document (look for the sentence beginning with "Medium or high risk changes" to locate it) to apply the LanguageTool suggestion..archon/workflows/design/design-brief-to-handoff.yaml (1)
1-40: LGTM — sequential design pipeline is coherent.The dependency chain (
design-brief→design-input→handoff-check→design-approval→ux-review-template) cleanly mirrors the command artifact flow (design-brief.md→handoff.md→ux-review.md), andworktree.enabled: falseis correct for this read-only/approval workflow.One thing worth noting:
ux-review-templaterunsdesign-ui-review, whose process step 1 reads$ARTIFACTS_DIR/development/implementation-report.md. At design-handoff time the implementation report normally won't exist yet. The command spec says "if present", so this is non-blocking, but consider whether runningdesign-ui-reviewhere is premature — its natural home is post-implementation (alongsideqa-pr-validation). If the intent is a pre-implementation UX/template review, a different command may convey intent more clearly.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.archon/workflows/design/design-brief-to-handoff.yaml around lines 1 - 40, The workflow currently runs the ux-review-template node (command: design-ui-review) immediately after design-approval, but design-ui-review expects an implementation-report at $ARTIFACTS_DIR/development/implementation-report.md "if present" and is more naturally run post-implementation; either move the ux-review-template node to a post-implementation/QA stage (e.g., after a qa-pr-validation node) or replace its command with a pre-implementation UX/template review command (create/use a command like design-ui-preflight) so the node's intent matches available artifacts and timing; update the nodes list accordingly (references: ux-review-template, design-ui-review, design-approval, qa-pr-validation)..archon/workflows/product/intake-to-prd.yaml (1)
14-72: LGTM — clean intake → PRD pipeline.Nodes, dependencies, and approval gating are coherent, and the captured approval responses feed the decision log as expected.
Two small observations (non-blocking):
The
classifynode returnsreadiness(ready/needs-more-information) but no node branches on it — execution proceeds toresearchandfoundation-gateregardless. That's acceptable sincefoundation-gateis a human approval that can short-circuit a not-ready intake, but if the intent is to skip research for already-ready requests (or pause for not-ready ones), awhen:onresearchwould express that.
$product-approval.outputin thedecision-logprompt relies on the expression engine handling hyphenated node ids in property-access positions. Worth confirming once for this PR (same concern applies tosecurity-risk-gate); if it works there, it works here.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.archon/workflows/product/intake-to-prd.yaml around lines 14 - 72, The classify node emits readiness but no downstream branching — add a conditional on the research node so it only runs when appropriate (e.g., only when classify.output.readiness == "needs-more-information" or the inverse if you prefer skipping research for ready requests) and update the decision-log prompt to reference hyphenated node outputs using bracket/explicit-expression access for nodes like product-approval and security-risk-gate (e.g., use the expression engine’s bracket notation to read the output of "product-approval" and "security-risk-gate") so the prompt reliably reads those captured approval responses.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.archon/commands/devops/devops-deployment-readiness.md:
- Around line 27-29: The "Blocked" verdict currently isn't gating downstream
steps; update either the command behavior or the workflow: modify the command
represented by the verdict (the output key "verdict") so that when it is
"Blocked" the command exits non-zero (failing the step), or update the workflow
node(s) in release-readiness.yaml that follow this task (the downstream jobs
"rollback-plan" and "devops-approval") to add a conditional check on
$deployment-readiness.output.verdict (e.g., a when/trigger_rule) so they only
run for allowed verdicts; pick one approach, implement the non-zero exit in the
command that emits "verdict" or add a when:/$deployment-readiness.output.verdict
gating to the rollback-plan and devops-approval nodes.
In @.archon/commands/qa/qa-pr-validation-report.md:
- Around line 18-20: The validation-report step in qa-pr-validation-report.md
currently reads test-plan.md and inspects logs but omits regression-selection
output; update the command/documentation so the process also reads
$ARTIFACTS_DIR/qa/regression-selection.md and incorporates its obligations into
the generated $ARTIFACTS_DIR/qa/validation-report.md, ensuring any required
regressions listed in regression-selection.md are reflected in the final report
and referenced when summarizing validation status.
In @.archon/commands/qa/qa-regression-selection.md:
- Around line 18-20: The regression-selection checklist currently omits
importing the upstream QA test plan; update the steps so the process explicitly
reads $ARTIFACTS_DIR/qa/test-plan.md (e.g., amend step 1 or insert a new step
before writing $ARTIFACTS_DIR/qa/regression-selection.md) so that the
function/step that "Read implementation and security artifacts" also ingests the
QA test plan and uses it to seed regression areas and scenarios (reference the
checklist items "Read implementation and security artifacts if present" and
"Write $ARTIFACTS_DIR/qa/regression-selection.md" to locate where to add the
read).
In @.archon/commands/services/services-feedback-to-product.md:
- Around line 18-21: Add an explicit PII/sensitive-data minimization step to the
services-feedback-to-product.md template (the feedback-to-product artifact
generation flow) so that before writing the artifact the author must
redact/obfuscate direct identifiers (names, emails, ticket IDs, phone numbers,
IPs, account IDs) or replace them with stable tokens, record only non-reversible
hashes if evidence must be preserved, and confirm redaction via a one-line
checklist; implement this as a required checklist item in the template and add
an automated reminder/snippet that shows common patterns to strip and a link to
the secure ephemeral store policy (apply the same change to the other feedback
template occurrences in the file).
In @.archon/workflows/development/plan-to-pr.yaml:
- Around line 12-35: The pipeline fails because the confirm-plan step (id:
confirm-plan / command: development-confirm-plan) outputs
development/implementation-plan.md while downstream steps (ids: implement,
validate, finalize-pr using archon-implement-tasks, archon-validate,
archon-finalize-pr) expect plan-context.md and/or plan-confirmation.md; add a
bridge step between confirm-plan and build-approval (or modify confirm-plan)
that renames or copies development/implementation-plan.md to the expected
artifact names (plan-context.md and plan-confirmation.md) so downstream commands
can find the inputs, or change development-confirm-plan to emit the expected
filenames directly; reference the ids confirm-plan, build-approval, implement,
validate, finalize-pr when making the change.
In @.archon/workflows/docs/docs-impact-and-release-notes.yaml:
- Around line 5-27: The description and node behavior are inconsistent: either
update the top-level description to state help/user-guide deltas are always
attempted, or implement a structured output from the docs-impact node (e.g.,
outputs help_needed and release_notes_needed) and add when: guards on the
help-update and release-notes nodes so they only run when those outputs are
true; specifically, modify the docs-impact command to emit JSON/structured
outputs like help_needed:true/false and wire those outputs into help-update and
release-notes via when conditions (and keep or adjust release-notes'
trigger_rule as needed).
In @.archon/workflows/security/security-risk-gate.yaml:
- Around line 80-84: The risk-acceptance job is currently tied to
security-approval, which can be skipped when approval_required == "false",
making medium-risk cases unreachable; to fix, either update the classifier logic
that sets approval_required (ensure it sets approval_required = "true" whenever
classify-security.output.risk_level is "medium" or "high"), or change the
risk-acceptance step (id: risk-acceptance) to depend directly on
classify-security instead of security-approval and add trigger_rule: all_done so
it always runs after classification (and then conditionally require an
acceptance artifact when risk_level ∈ {medium, high}); refer to the symbols
classify-security, security-approval, risk-acceptance, approval_required,
risk_level and trigger_rule when making the change.
- Around line 60-64: The current when condition on the dependency-review step
uses "$classify-security.output.triggers != ''" which is too broad and causes
the security-dependency-review job (id: dependency-review, command:
security-dependency-review) to run for any free-form trigger; update the gate to
a dependency-specific signal instead — either change the classifier to emit a
boolean/enum like dependency_changed (add dependency_changed to
classify-security output and gate with
"$classify-security.output.dependency_changed == 'true'") or, if the engine
supports string matching, narrow the when to look for dependency keywords in
classify-security.output.triggers (e.g., match "dependency|lockfile|manifest")
so security-dependency-review only executes when dependency-related changes are
detected.
In @.archon/workflows/services/customer-readiness.yaml:
- Around line 24-33: The feedback-loop node currently depends_on
services-approval but lacks gating, so it fires on rejection; update the
feedback-loop node to include the same gating pattern used elsewhere (add a when
condition evaluating the captured approval response from services-approval, e.g.
check services-approval.response == "approved") and set an appropriate
trigger_rule (e.g., trigger_rule: on_success) so it only runs for approved
outcomes; also make ids consistent by renaming either services-approval to match
the shorter style or renaming customer-impact, implementation-readiness,
feedback-loop to a namespaced style for consistent node id naming.
---
Nitpick comments:
In @.archon/commands/docs/docs-impact.md:
- Around line 36-38: The "User-Facing Release Notes" section in docs-impact.md
conflicts with the separate docs-release-notes command; update the artifact so
it no longer duplicates the canonical release notes by either (a) turning the
"User-Facing Release Notes" block into a short pointer/summary that explicitly
references the docs-release-notes command as the source of truth, or (b)
renaming the section to something unambiguous like "Release Notes Triggers" or
"Customer-Visible Changes" and keeping only trigger/impact guidance. Locate the
heading "User-Facing Release Notes" (and adjacent "Internal Enablement Notes")
and modify its content and title accordingly so consumers know this file is not
the authoritative release-notes copy.
In @.archon/commands/docs/docs-release-notes.md:
- Around line 18-20: Update the release-notes step in docs-release-notes.md to
include an explicit redaction rule for security-derived artifacts: when reading
security artifacts (tokens, internal endpoints, exploit details, stack traces,
credentials), redact or omit any sensitive internals and only surface high-level
impact and mitigations in the user-facing release notes written to
$ARTIFACTS_DIR/docs/release-notes.md; reference this rule in the steps that read
security artifacts so the authoring workflow for writing release-notes.md
enforces exclusion of secrets and internal-only details.
In @.archon/commands/security/security-dependency-review.md:
- Around line 16-21: Add an explicit "no dependency changes" outcome to the
dependency review output: when inspecting
manifests/lockfiles/Dockerfiles/install scripts yields no changes, write a clear
line such as "Verdict: not applicable" into the generated artifact (the file
referenced by Write $ARTIFACTS_DIR/security/dependency-review.md) and update the
template/logic that produces lines 38-40 to emit this default verdict to avoid
speculative findings.
In @.archon/workflows/design/design-brief-to-handoff.yaml:
- Around line 1-40: The workflow currently runs the ux-review-template node
(command: design-ui-review) immediately after design-approval, but
design-ui-review expects an implementation-report at
$ARTIFACTS_DIR/development/implementation-report.md "if present" and is more
naturally run post-implementation; either move the ux-review-template node to a
post-implementation/QA stage (e.g., after a qa-pr-validation node) or replace
its command with a pre-implementation UX/template review command (create/use a
command like design-ui-preflight) so the node's intent matches available
artifacts and timing; update the nodes list accordingly (references:
ux-review-template, design-ui-review, design-approval, qa-pr-validation).
In @.archon/workflows/product/intake-to-prd.yaml:
- Around line 14-72: The classify node emits readiness but no downstream
branching — add a conditional on the research node so it only runs when
appropriate (e.g., only when classify.output.readiness ==
"needs-more-information" or the inverse if you prefer skipping research for
ready requests) and update the decision-log prompt to reference hyphenated node
outputs using bracket/explicit-expression access for nodes like product-approval
and security-risk-gate (e.g., use the expression engine’s bracket notation to
read the output of "product-approval" and "security-risk-gate") so the prompt
reliably reads those captured approval responses.
In @.github/pull_request_template.md:
- Around line 106-109: Add a dedicated placeholder for the security gate
artifact and verdict next to the existing "security-risk-gate" prompt: add two
explicit fields such as "security-risk-gate-link: (URL to artifact)" and
"security-risk-gate-verdict: (Pass/Fail/Not applicable)" so reviewers can record
the gate result and link; update the block currently containing "If any `Yes`,
run or link `security-risk-gate`" to require those fields and keep the existing
risk/mitigation lines for consistency.
In `@docs/archon/workflows/cross-functional-rollout.md`:
- Around line 1-156: Replace the phrasing "Medium or high risk changes require
security approval or documented risk acceptance before merge or release." with
"Medium- or high-risk changes require security approval or documented risk
acceptance before merge or release." in the document (look for the sentence
beginning with "Medium or high risk changes" to locate it) to apply the
LanguageTool suggestion.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: b6583d4d-ad90-4e50-987d-043d60fa4cc3
📒 Files selected for processing (38)
.archon/commands/design/design-brief.md.archon/commands/design/design-handoff-check.md.archon/commands/design/design-ui-review.md.archon/commands/development/development-confirm-plan.md.archon/commands/development/development-implementation-report.md.archon/commands/devops/devops-deployment-readiness.md.archon/commands/devops/devops-incident-followup.md.archon/commands/devops/devops-rollback-plan.md.archon/commands/docs/docs-help-update.md.archon/commands/docs/docs-impact.md.archon/commands/docs/docs-release-notes.md.archon/commands/product/product-intake-research.md.archon/commands/product/product-prd-generate.md.archon/commands/product/product-scope-change-review.md.archon/commands/qa/qa-pr-validation-report.md.archon/commands/qa/qa-regression-selection.md.archon/commands/qa/qa-test-plan.md.archon/commands/security/security-dependency-review.md.archon/commands/security/security-risk-acceptance.md.archon/commands/security/security-risk-review.md.archon/commands/security/security-secrets-permissions-review.md.archon/commands/security/security-threat-model.md.archon/commands/services/services-customer-impact.md.archon/commands/services/services-feedback-to-product.md.archon/commands/services/services-implementation-readiness.md.archon/workflows/design/design-brief-to-handoff.yaml.archon/workflows/development/plan-to-pr.yaml.archon/workflows/devops/release-readiness.yaml.archon/workflows/docs/docs-impact-and-release-notes.yaml.archon/workflows/product/intake-to-prd.yaml.archon/workflows/qa/pr-validation.yaml.archon/workflows/security/security-risk-gate.yaml.archon/workflows/services/customer-readiness.yaml.github/ISSUE_TEMPLATE/customer_request.md.github/ISSUE_TEMPLATE/incident_followup.md.github/ISSUE_TEMPLATE/security_sensitive_change.md.github/pull_request_template.mddocs/archon/workflows/cross-functional-rollout.md
Comment on lines
+27
to
+29
| ## Verdict | ||
|
|
||
| Ready / Ready with caveats / Blocked |
There was a problem hiding this comment.
“Blocked” verdict isn’t actionable in the consuming workflow.
The artifact defines a Blocked verdict, but .archon/workflows/devops/release-readiness.yaml runs rollback-plan and devops-approval unconditionally after this node — there is no when:/trigger_rule gating on the verdict. As written, a Blocked outcome still progresses to rollback planning and approval, which dilutes the verdict’s meaning and risks deployments being approved despite known blockers.
Recommend either:
- documenting in this command spec that on
Blockedthe command must fail (non-zero / explicit signal) so the workflow short-circuits, or - updating
release-readiness.yamlto gate downstream nodes on$deployment-readiness.output.verdict.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/commands/devops/devops-deployment-readiness.md around lines 27 - 29,
The "Blocked" verdict currently isn't gating downstream steps; update either the
command behavior or the workflow: modify the command represented by the verdict
(the output key "verdict") so that when it is "Blocked" the command exits
non-zero (failing the step), or update the workflow node(s) in
release-readiness.yaml that follow this task (the downstream jobs
"rollback-plan" and "devops-approval") to add a conditional check on
$deployment-readiness.output.verdict (e.g., a when/trigger_rule) so they only
run for allowed verdicts; pick one approach, implement the non-zero exit in the
command that emits "verdict" or add a when:/$deployment-readiness.output.verdict
gating to the rollback-plan and devops-approval nodes.
Comment on lines
+18
to
+20
| 1. Read `$ARTIFACTS_DIR/qa/test-plan.md` if present. | ||
| 2. Inspect available validation output, test logs, screenshots, and PR metadata. | ||
| 3. Write `$ARTIFACTS_DIR/qa/validation-report.md`. |
There was a problem hiding this comment.
Validation report should consume regression-selection output.
Given the workflow order, this command should also read $ARTIFACTS_DIR/qa/regression-selection.md; otherwise the report can miss required regression obligations from the prior step.
Suggested update
-1. Read `$ARTIFACTS_DIR/qa/test-plan.md` if present.
+1. Read `$ARTIFACTS_DIR/qa/test-plan.md` and `$ARTIFACTS_DIR/qa/regression-selection.md` if present.
2. Inspect available validation output, test logs, screenshots, and PR metadata.
3. Write `$ARTIFACTS_DIR/qa/validation-report.md`.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/commands/qa/qa-pr-validation-report.md around lines 18 - 20, The
validation-report step in qa-pr-validation-report.md currently reads
test-plan.md and inspects logs but omits regression-selection output; update the
command/documentation so the process also reads
$ARTIFACTS_DIR/qa/regression-selection.md and incorporates its obligations into
the generated $ARTIFACTS_DIR/qa/validation-report.md, ensuring any required
regressions listed in regression-selection.md are reflected in the final report
and referenced when summarizing validation status.
Comment on lines
+18
to
+20
| 1. Read implementation and security artifacts if present. | ||
| 2. Inspect changed files and related modules. | ||
| 3. Write `$ARTIFACTS_DIR/qa/regression-selection.md`. |
There was a problem hiding this comment.
Regression selection is missing the upstream QA test plan input.
This step should explicitly read $ARTIFACTS_DIR/qa/test-plan.md; otherwise, required regression areas can diverge from the planned scenarios created earlier in the workflow.
Suggested update
-1. Read implementation and security artifacts if present.
-2. Inspect changed files and related modules.
+1. Read `$ARTIFACTS_DIR/qa/test-plan.md` if present, plus implementation and security artifacts.
+2. Inspect changed files and related modules.
3. Write `$ARTIFACTS_DIR/qa/regression-selection.md`.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 1. Read implementation and security artifacts if present. | |
| 2. Inspect changed files and related modules. | |
| 3. Write `$ARTIFACTS_DIR/qa/regression-selection.md`. | |
| 1. Read `$ARTIFACTS_DIR/qa/test-plan.md` if present, plus implementation and security artifacts. | |
| 2. Inspect changed files and related modules. | |
| 3. Write `$ARTIFACTS_DIR/qa/regression-selection.md`. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/commands/qa/qa-regression-selection.md around lines 18 - 20, The
regression-selection checklist currently omits importing the upstream QA test
plan; update the steps so the process explicitly reads
$ARTIFACTS_DIR/qa/test-plan.md (e.g., amend step 1 or insert a new step before
writing $ARTIFACTS_DIR/qa/regression-selection.md) so that the function/step
that "Read implementation and security artifacts" also ingests the QA test plan
and uses it to seed regression areas and scenarios (reference the checklist
items "Read implementation and security artifacts if present" and "Write
$ARTIFACTS_DIR/qa/regression-selection.md" to locate where to add the read).
Comment on lines
+18
to
+21
| 1. Extract customer context, problem, workaround, urgency, and business impact. | ||
| 2. Identify whether the feedback is a bug, feature, enablement gap, or service request. | ||
| 3. Write `$ARTIFACTS_DIR/services/feedback-to-product.md`. | ||
|
|
There was a problem hiding this comment.
Add PII/sensitive-data minimization requirements before writing artifacts.
The template captures customer context/evidence but does not require redaction or minimization. That can leak identifiers/tickets/emails into persistent workflow artifacts.
Proposed hardening
## Process
1. Extract customer context, problem, workaround, urgency, and business impact.
2. Identify whether the feedback is a bug, feature, enablement gap, or service request.
-3. Write `$ARTIFACTS_DIR/services/feedback-to-product.md`.
+3. Remove or mask sensitive customer data (names, emails, account IDs, private URLs, secrets) unless strictly required.
+4. Write `$ARTIFACTS_DIR/services/feedback-to-product.md`.
## Artifact Format
@@
## Customer Context
+Use role/segment-level descriptors; avoid direct personal identifiers unless explicitly required.
@@
## Evidence
+Reference source artifacts/links without copying raw sensitive payloads.Also applies to: 27-32
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/commands/services/services-feedback-to-product.md around lines 18 -
21, Add an explicit PII/sensitive-data minimization step to the
services-feedback-to-product.md template (the feedback-to-product artifact
generation flow) so that before writing the artifact the author must
redact/obfuscate direct identifiers (names, emails, ticket IDs, phone numbers,
IPs, account IDs) or replace them with stable tokens, record only non-reversible
hashes if evidence must be preserved, and confirm redaction via a one-line
checklist; implement this as a required checklist item in the template and add
an automated reminder/snippet that shows common patterns to strip and a link to
the secure ephemeral store policy (apply the same change to the other feedback
template occurrences in the file).
Comment on lines
+12
to
+35
| - id: confirm-plan | ||
| command: development-confirm-plan | ||
| context: fresh | ||
|
|
||
| - id: build-approval | ||
| approval: | ||
| message: "Approve implementation scope before code changes begin." | ||
| capture_response: true | ||
| depends_on: [confirm-plan] | ||
|
|
||
| - id: implement | ||
| command: archon-implement-tasks | ||
| depends_on: [build-approval] | ||
| context: fresh | ||
| model: opus[1m] | ||
|
|
||
| - id: validate | ||
| command: archon-validate | ||
| depends_on: [implement] | ||
| context: fresh | ||
|
|
||
| - id: finalize-pr | ||
| command: archon-finalize-pr | ||
| depends_on: [validate] |
There was a problem hiding this comment.
Artifact contract mismatch will break downstream implementation/validation/finalization.
development-confirm-plan produces development/implementation-plan.md, but archon-implement-tasks and later default steps read plan-context.md/plan-confirmation.md. As wired, the pipeline can’t satisfy downstream required inputs.
Suggested workflow bridge node
nodes:
- id: confirm-plan
command: development-confirm-plan
context: fresh
+ - id: normalize-plan-artifacts
+ prompt: |
+ Read `$ARTIFACTS_DIR/development/implementation-plan.md` and write:
+ - `$ARTIFACTS_DIR/plan-context.md`
+ - `$ARTIFACTS_DIR/plan-confirmation.md`
+ Ensure status is explicit (CONFIRMED / PROCEED WITH CAUTION) and include validation commands.
+ depends_on: [confirm-plan]
+ context: fresh
+
- id: build-approval
approval:
message: "Approve implementation scope before code changes begin."
capture_response: true
- depends_on: [confirm-plan]
+ depends_on: [normalize-plan-artifacts]
- id: implement
command: archon-implement-tasks
depends_on: [build-approval]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| - id: confirm-plan | |
| command: development-confirm-plan | |
| context: fresh | |
| - id: build-approval | |
| approval: | |
| message: "Approve implementation scope before code changes begin." | |
| capture_response: true | |
| depends_on: [confirm-plan] | |
| - id: implement | |
| command: archon-implement-tasks | |
| depends_on: [build-approval] | |
| context: fresh | |
| model: opus[1m] | |
| - id: validate | |
| command: archon-validate | |
| depends_on: [implement] | |
| context: fresh | |
| - id: finalize-pr | |
| command: archon-finalize-pr | |
| depends_on: [validate] | |
| - id: confirm-plan | |
| command: development-confirm-plan | |
| context: fresh | |
| - id: normalize-plan-artifacts | |
| prompt: | | |
| Read `$ARTIFACTS_DIR/development/implementation-plan.md` and write: | |
| - `$ARTIFACTS_DIR/plan-context.md` | |
| - `$ARTIFACTS_DIR/plan-confirmation.md` | |
| Ensure status is explicit (CONFIRMED / PROCEED WITH CAUTION) and include validation commands. | |
| depends_on: [confirm-plan] | |
| context: fresh | |
| - id: build-approval | |
| approval: | |
| message: "Approve implementation scope before code changes begin." | |
| capture_response: true | |
| depends_on: [normalize-plan-artifacts] | |
| - id: implement | |
| command: archon-implement-tasks | |
| depends_on: [build-approval] | |
| context: fresh | |
| model: opus[1m] | |
| - id: validate | |
| command: archon-validate | |
| depends_on: [implement] | |
| context: fresh | |
| - id: finalize-pr | |
| command: archon-finalize-pr | |
| depends_on: [validate] |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/workflows/development/plan-to-pr.yaml around lines 12 - 35, The
pipeline fails because the confirm-plan step (id: confirm-plan / command:
development-confirm-plan) outputs development/implementation-plan.md while
downstream steps (ids: implement, validate, finalize-pr using
archon-implement-tasks, archon-validate, archon-finalize-pr) expect
plan-context.md and/or plan-confirmation.md; add a bridge step between
confirm-plan and build-approval (or modify confirm-plan) that renames or copies
development/implementation-plan.md to the expected artifact names
(plan-context.md and plan-confirmation.md) so downstream commands can find the
inputs, or change development-confirm-plan to emit the expected filenames
directly; reference the ids confirm-plan, build-approval, implement, validate,
finalize-pr when making the change.
Comment on lines
+5
to
+27
| Does: Reviews docs impact -> drafts help/user-guide delta when needed -> drafts release notes -> | ||
| waits for docs approval. | ||
| NOT for: Product requirements or QA validation. | ||
|
|
||
| provider: claude | ||
| interactive: true | ||
| worktree: | ||
| enabled: false | ||
|
|
||
| nodes: | ||
| - id: docs-impact | ||
| command: docs-impact | ||
| context: fresh | ||
|
|
||
| - id: help-update | ||
| command: docs-help-update | ||
| depends_on: [docs-impact] | ||
| context: fresh | ||
|
|
||
| - id: release-notes | ||
| command: docs-release-notes | ||
| depends_on: [docs-impact, help-update] | ||
| trigger_rule: all_done |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify whether docs-impact command emits a structured flag we could gate on
fd -t f 'docs-impact.md' .archon/commands -x cat {}Repository: coleam00/Archon
Length of output: 912
🏁 Script executed:
#!/bin/bash
# Search for examples of when: conditions in workflows to understand output access patterns
rg 'when:' .archon/workflows --type yaml -A 2 -B 2 | head -100Repository: coleam00/Archon
Length of output: 8232
🏁 Script executed:
#!/bin/bash
# Check if docs-impact emits any JSON output or just markdown
fd -t f 'docs-impact' .archon -x grep -l 'json\|output\|structured' {} \;Repository: coleam00/Archon
Length of output: 113
🏁 Script executed:
#!/bin/bash
# Look for workflow node output syntax examples or documentation
fd -t f '\.md$' .archon -x grep -l 'output\|when:.*\$' {} \;Repository: coleam00/Archon
Length of output: 806
🏁 Script executed:
#!/bin/bash
# Find and read the docs-impact command specification
fd -t f 'docs-impact' .archon/commands -name '*.md' -exec cat {} \;Repository: coleam00/Archon
Length of output: 290
🏁 Script executed:
#!/bin/bash
# For comparison, check how classify-security documents its output format
fd -t f 'classify-security' .archon/commands -name '*.md' -exec cat {} \;Repository: coleam00/Archon
Length of output: 290
🏁 Script executed:
#!/bin/bash
# Find docs-impact command files and read them
fd 'docs-impact' .archon/commands -type f | xargs -I {} sh -c 'echo "=== {} ===" && cat {}'Repository: coleam00/Archon
Length of output: 230
🏁 Script executed:
#!/bin/bash
# Find classify-security command files for comparison
fd 'classify-security' .archon/commands -type f | xargs -I {} sh -c 'echo "=== {} ===" && cat {}'Repository: coleam00/Archon
Length of output: 230
🏁 Script executed:
#!/bin/bash
# Find docs-impact command files
fd 'docs-impact' .archon/commands --type file | xargs -I {} sh -c 'echo "=== {} ===" && cat {}'Repository: coleam00/Archon
Length of output: 6505
🏁 Script executed:
#!/bin/bash
# Find classify-security command files for comparison
fd 'classify-security' .archon/commands --type file | xargs -I {} sh -c 'echo "=== {} ===" && cat {}'Repository: coleam00/Archon
Length of output: 41
🏁 Script executed:
#!/bin/bash
# Check the classify-security command to see how it documents output structure
fd 'classify-security' .archon/commands --type file | xargs catRepository: coleam00/Archon
Length of output: 41
🏁 Script executed:
#!/bin/bash
# Search for how other commands document their output structure (JSON fields)
rg 'output.*:' .archon/commands --type markdown -A 2 | head -80Repository: coleam00/Archon
Length of output: 2011
🏁 Script executed:
#!/bin/bash
# Check the actual workflow file to see all nodes and dependencies
cat .archon/workflows/docs/docs-impact-and-release-notes.yamlRepository: coleam00/Archon
Length of output: 1079
🏁 Script executed:
#!/bin/bash
# Search for docs-help-update and docs-release-notes commands to understand their dependencies
fd 'docs-help-update\|docs-release-notes' .archon/commands --type file | xargs catRepository: coleam00/Archon
Length of output: 41
🏁 Script executed:
#!/bin/bash
# Check if any docs- commands emit JSON output by searching their specs
rg 'json|JSON|output.*format' .archon/commands/docs --type markdown -A 3Repository: coleam00/Archon
Length of output: 41
Description says help-update runs "when needed" but node runs unconditionally.
The workflow description (lines 5–7) states that help-update is drafted "when needed", but the help-update node (lines 19–22) has no when: guard and runs unconditionally after docs-impact completes.
Either:
- Update the description to say help/user-guide delta is always drafted (the command itself determines if there's anything to output), or
- Add a structured output flag from
docs-impactthathelp-updatecan key off (this would require thedocs-impactcommand to emit JSON fields likehelp_needed: true|false, which currently isn't documented).
The same applies to release-notes: the trigger_rule: all_done permits it to run even if help-update fails, which is reasonable, but a when: condition would let it skip cleanly when there's genuinely nothing to release-note.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/workflows/docs/docs-impact-and-release-notes.yaml around lines 5 -
27, The description and node behavior are inconsistent: either update the
top-level description to state help/user-guide deltas are always attempted, or
implement a structured output from the docs-impact node (e.g., outputs
help_needed and release_notes_needed) and add when: guards on the help-update
and release-notes nodes so they only run when those outputs are true;
specifically, modify the docs-impact command to emit JSON/structured outputs
like help_needed:true/false and wire those outputs into help-update and
release-notes via when conditions (and keep or adjust release-notes'
trigger_rule as needed).
Comment on lines
+60
to
+64
| - id: dependency-review | ||
| command: security-dependency-review | ||
| depends_on: [classify-security] | ||
| when: "$classify-security.output.triggers != ''" | ||
| context: fresh |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Verify how the workflow expression engine tokenizes hyphenated node ids and property access.
fd -e ts -e tsx . packages/workflows/src 2>/dev/null | head -50
rg -nP -C3 '\$[A-Za-z][A-Za-z0-9_-]*\.output' packages/workflows/src 2>/dev/null
ast-grep --pattern 'function evaluateExpression($_, $_) { $$$ }'
ast-grep --pattern 'function substitute($_, $_) { $$$ }'
rg -nP -C2 'nodeId|node_id|\\bid\\b.*regex|hyphen' packages/workflows/src 2>/dev/null | head -80Repository: coleam00/Archon
Length of output: 50372
when condition for dependency-review is likely too permissive.
when: "$classify-security.output.triggers != ''" will fire the dependency review for almost every classification because the classify-security prompt asks for a free-form triggers string describing why review was needed (auth, secrets, infra, etc.) — it doesn't restrict population to dependency-only signals. As a result, security-dependency-review will run even when there are no manifest/lockfile/IaC changes.
Consider gating on a dependency-specific signal instead, either by:
- Adding a separate boolean field to the classifier output schema (e.g.,
dependency_changed: "true"|"false"), or - Matching keywords in
triggersif the engine supports it.
Suggested schema-based gate
output_format:
type: object
properties:
review_required:
type: string
enum: ["true", "false"]
risk_level:
type: string
enum: ["low", "medium", "high"]
approval_required:
type: string
enum: ["true", "false"]
+ dependency_changed:
+ type: string
+ enum: ["true", "false"]
triggers:
type: string
reasoning:
type: string
- required: [review_required, risk_level, approval_required, triggers, reasoning]
+ required: [review_required, risk_level, approval_required, dependency_changed, triggers, reasoning]
@@
- id: dependency-review
command: security-dependency-review
depends_on: [classify-security]
- when: "$classify-security.output.triggers != ''"
+ when: "$classify-security.output.dependency_changed == 'true'"
context: fresh🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/workflows/security/security-risk-gate.yaml around lines 60 - 64, The
current when condition on the dependency-review step uses
"$classify-security.output.triggers != ''" which is too broad and causes the
security-dependency-review job (id: dependency-review, command:
security-dependency-review) to run for any free-form trigger; update the gate to
a dependency-specific signal instead — either change the classifier to emit a
boolean/enum like dependency_changed (add dependency_changed to
classify-security output and gate with
"$classify-security.output.dependency_changed == 'true'") or, if the engine
supports string matching, narrow the when to look for dependency keywords in
classify-security.output.triggers (e.g., match "dependency|lockfile|manifest")
so security-dependency-review only executes when dependency-related changes are
detected.
Comment on lines
+80
to
+84
| - id: risk-acceptance | ||
| command: security-risk-acceptance | ||
| depends_on: [security-approval] | ||
| when: "$classify-security.output.risk_level == 'medium' || $classify-security.output.risk_level == 'high'" | ||
| context: fresh |
There was a problem hiding this comment.
risk-acceptance may be unreachable for medium risk without explicit approval.
risk-acceptance depends on security-approval, which only runs when approval_required == 'true'. If the classifier returns risk_level: "medium" but approval_required: "false", security-approval is skipped → risk-acceptance is skipped (default trigger_rule) and the medium-risk classification proceeds without an acceptance artifact. Verify whether the intent is "medium risk always demands either approval or documented acceptance"; if so, either:
- Force
approval_required = "true"wheneverrisk_level ∈ {medium, high}in the classifier prompt, or - Have
risk-acceptancedepend onclassify-security(withtrigger_rule: all_done) instead ofsecurity-approval.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/workflows/security/security-risk-gate.yaml around lines 80 - 84, The
risk-acceptance job is currently tied to security-approval, which can be skipped
when approval_required == "false", making medium-risk cases unreachable; to fix,
either update the classifier logic that sets approval_required (ensure it sets
approval_required = "true" whenever classify-security.output.risk_level is
"medium" or "high"), or change the risk-acceptance step (id: risk-acceptance) to
depend directly on classify-security instead of security-approval and add
trigger_rule: all_done so it always runs after classification (and then
conditionally require an acceptance artifact when risk_level ∈ {medium, high});
refer to the symbols classify-security, security-approval, risk-acceptance,
approval_required, risk_level and trigger_rule when making the change.
Comment on lines
+24
to
+33
| - id: services-approval | ||
| approval: | ||
| message: "Approve customer readiness for launch, or reject with enablement/customer blockers." | ||
| capture_response: true | ||
| depends_on: [implementation-readiness] | ||
|
|
||
| - id: feedback-loop | ||
| command: services-feedback-to-product | ||
| depends_on: [services-approval] | ||
| context: fresh |
There was a problem hiding this comment.
feedback-loop runs even when services approval is rejected.
feedback-loop only declares depends_on: [services-approval] with no when: or trigger_rule: gating on the captured approval response. As a result, rejection of customer readiness still triggers the “feedback to product” step, which conflates approved-launch feedback with rejection signals.
Other workflows in this PR gate downstream nodes (e.g., .archon/workflows/security/security-risk-gate.yaml uses when: and trigger_rule); apply the same pattern here, or explicitly document that feedback-loop is intended to fire on both outcomes (and have it branch internally).
Minor nit while you're here: node id naming is inconsistent — services-approval is namespaced, but customer-impact, implementation-readiness, and feedback-loop are not. Pick one convention.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.archon/workflows/services/customer-readiness.yaml around lines 24 - 33, The
feedback-loop node currently depends_on services-approval but lacks gating, so
it fires on rejection; update the feedback-loop node to include the same gating
pattern used elsewhere (add a when condition evaluating the captured approval
response from services-approval, e.g. check services-approval.response ==
"approved") and set an appropriate trigger_rule (e.g., trigger_rule: on_success)
so it only runs for approved outcomes; also make ids consistent by renaming
either services-approval to match the shorter style or renaming customer-impact,
implementation-readiness, feedback-loop to a namespaced style for consistent
node id naming.
There was a problem hiding this comment.
🧹 Nitpick comments (2)
docs/archon/workflows/cross-functional-rollout.md (1)
116-116: Use hyphen for compound adjective.Same issue as in
user-guide.md: "Medium or high risk changes" should be "Medium-risk or high-risk changes" for grammatical clarity.✏️ Proposed fix
-Medium or high risk changes require security approval or documented risk acceptance before merge or release. +Medium-risk or high-risk changes require security approval or documented risk acceptance before merge or release.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/archon/workflows/cross-functional-rollout.md` at line 116, Replace the unhyphenated compound adjective "Medium or high risk changes" with hyphenated forms: change the phrase to "Medium-risk or high-risk changes" in the text shown (the sentence starting with "Medium or high risk changes require security approval or documented risk acceptance before merge or release."); update any identical occurrences in this document to use the hyphenated compound adjectives for grammatical consistency.docs/archon/workflows/user-guide.md (1)
121-121: Use hyphen for compound adjective.The phrase "Medium or high risk changes" should use a hyphen: "Medium- or high-risk changes" (or more clearly: "Medium-risk or high-risk changes"). Compound adjectives before nouns require hyphens for clarity.
✏️ Proposed fix
-Medium or high risk changes require security approval or documented risk acceptance before merge or release. +Medium-risk or high-risk changes require security approval or documented risk acceptance before merge or release.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/archon/workflows/user-guide.md` at line 121, Update the sentence "Medium or high risk changes require security approval or documented risk acceptance before merge or release." to use hyphenated compound adjectives; change it to either "Medium- or high-risk changes require security approval or documented risk acceptance before merge or release." or "Medium-risk or high-risk changes require security approval or documented risk acceptance before merge or release." Ensure the hyphenation is applied to the compound adjective before "changes".
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/archon/workflows/cross-functional-rollout.md`:
- Line 116: Replace the unhyphenated compound adjective "Medium or high risk
changes" with hyphenated forms: change the phrase to "Medium-risk or high-risk
changes" in the text shown (the sentence starting with "Medium or high risk
changes require security approval or documented risk acceptance before merge or
release."); update any identical occurrences in this document to use the
hyphenated compound adjectives for grammatical consistency.
In `@docs/archon/workflows/user-guide.md`:
- Line 121: Update the sentence "Medium or high risk changes require security
approval or documented risk acceptance before merge or release." to use
hyphenated compound adjectives; change it to either "Medium- or high-risk
changes require security approval or documented risk acceptance before merge or
release." or "Medium-risk or high-risk changes require security approval or
documented risk acceptance before merge or release." Ensure the hyphenation is
applied to the compound adjective before "changes".
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: e3722402-df82-46d6-8680-dbf136c8d02f
📒 Files selected for processing (3)
docs/archon/workflows/cross-functional-rollout.mddocs/archon/workflows/personas.mddocs/archon/workflows/user-guide.md
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@docs/archon/workflows/cross-functional-rollout.md`:
- Line 117: Replace the unhyphenated phrase in the sentence "Medium or high risk
changes require security approval or documented risk acceptance before merge or
release." by hyphenating the compound modifier so it reads "Medium or high-risk
changes require security approval or documented risk acceptance before merge or
release."; update the exact phrase "high risk changes" to "high-risk changes" to
improve readability.
In `@docs/archon/workflows/pilot-pitch.md`:
- Line 69: Update the phrasing in the Security step where the sentence currently
reads "Security reviews triggered risk areas" — change it to the grammatically
correct and unambiguous form, e.g., "Security reviews trigger risk areas" (if
active voice) or "Security reviews triggered risk areas" only if you add a clear
subject to make passive voice correct; locate the exact string "Security reviews
triggered risk areas" in the pilot-pitch.md content and replace it with the
chosen corrected wording.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 12ed6fda-fc63-4ade-94ab-6597506d49e4
📒 Files selected for processing (2)
docs/archon/workflows/cross-functional-rollout.mddocs/archon/workflows/pilot-pitch.md
| - External network exposure | ||
| - Any PR label: `security-review`, `release-risk`, `customer-data`, `auth` | ||
|
|
||
| Medium or high risk changes require security approval or documented risk acceptance before merge or release. |
There was a problem hiding this comment.
Hyphenate compound modifier for readability.
Use “high-risk changes” in Line 117.
✏️ Proposed wording fix
-Medium or high risk changes require security approval or documented risk acceptance before merge or release.
+Medium- or high-risk changes require security approval or documented risk acceptance before merge or release.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| Medium or high risk changes require security approval or documented risk acceptance before merge or release. | |
| Medium- or high-risk changes require security approval or documented risk acceptance before merge or release. |
🧰 Tools
🪛 LanguageTool
[grammar] ~117-~117: Use a hyphen to join words.
Context: ... customer-data, auth Medium or high risk changes require security approval o...
(QB_NEW_EN_HYPHEN)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/archon/workflows/cross-functional-rollout.md` at line 117, Replace the
unhyphenated phrase in the sentence "Medium or high risk changes require
security approval or documented risk acceptance before merge or release." by
hyphenating the compound modifier so it reads "Medium or high-risk changes
require security approval or documented risk acceptance before merge or
release."; update the exact phrase "high risk changes" to "high-risk changes" to
improve readability.
| 1. Product clarifies the request and writes a PRD. | ||
| 2. Design turns the PRD into UX handoff. | ||
| 3. Development builds in an isolated worktree. | ||
| 4. Security reviews triggered risk areas. |
There was a problem hiding this comment.
Fix verb agreement in the Security step.
Line 69 reads “Security reviews triggered risk areas,” which is grammatically incorrect and ambiguous in an execution checklist. Use “Security reviews triggered risk areas” only if passive is intended with a subject, or more directly: “Security reviews trigger risk areas.”
✏️ Proposed wording fix
-4. Security reviews triggered risk areas.
+4. Security reviews trigger risk areas.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| 4. Security reviews triggered risk areas. | |
| 4. Security reviews trigger risk areas. |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@docs/archon/workflows/pilot-pitch.md` at line 69, Update the phrasing in the
Security step where the sentence currently reads "Security reviews triggered
risk areas" — change it to the grammatically correct and unambiguous form, e.g.,
"Security reviews trigger risk areas" (if active voice) or "Security reviews
triggered risk areas" only if you add a clear subject to make passive voice
correct; locate the exact string "Security reviews triggered risk areas" in the
pilot-pitch.md content and replace it with the chosen corrected wording.
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
3 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
Describe this PR in 2-5 bullets:
UX Journey
Before
After
Architecture Diagram
Before
After
Connection inventory (list every module-to-module edge, mark changes):
Label Snapshot
risk: low|medium|highsize: XS|S|M|L|XLcore|workflows|isolation|git|adapters|server|web|cli|paths|config|docs|dependencies|ci|tests|skills<scope>:<component>(e.g.workflows:executor,adapters:slack,core:orchestrator)Change Metadata
bug|feature|refactor|docs|security|chorecore|workflows|isolation|git|adapters|server|web|cli|paths|multiLinked Issue
Validation Evidence (required)
Commands and result summary:
Security Impact (required)
Yes/No)Yes/No)Yes/No)Yes/No)Yes, describe risk and mitigation:Compatibility / Migration
Yes/No)Yes/No)Yes/No)Human Verification (required)
What was personally validated beyond CI:
Side Effects / Blast Radius (required)
Rollback Plan (required)
Risks and Mitigations
List real risks in this PR (or write
None).Summary by CodeRabbit
New Features
Documentation