{"owner":"coleam00","repo":"Archon","hasSkills":true,"totalSkillsCount":139,"totalTokensCount":342267,"categories":["subagent-persona","command-prompt","anthropic-skill","root-instruction","claude-rule","plugin-manifest"],"hasMcp":false,"mcpConfig":null,"found":[".claude/agents/code-reviewer.md",".claude/agents/code-simplifier.md",".claude/agents/codebase-analyst.md",".claude/agents/codebase-explorer.md",".claude/agents/comment-analyzer.md",".claude/agents/docs-impact.md",".claude/agents/pr-test-analyzer.md",".claude/agents/rulecheck-agent.md",".claude/agents/sdk-verifier.md",".claude/agents/silent-failure-hunter.md",".claude/agents/triage-agent.md",".claude/agents/type-design-analyzer.md",".claude/agents/web-researcher.md",".claude/commands/commit.md",".claude/commands/create-command.md",".claude/commands/execute.md",".claude/commands/github_bug_fix/implement-fix.md",".claude/commands/github_bug_fix/rca.md",".claude/commands/handoff.md",".claude/commands/plan-feature.md",".claude/commands/prime-backend.md",".claude/commands/prime-frontend.md",".claude/commands/prime-isolation.md",".claude/commands/prime-workflows.md",".claude/commands/prime.md",".claude/commands/review-doc.md",".claude/commands/validate.md",".claude/commands/validation/code-review-fix.md",".claude/commands/validation/code-review.md",".claude/commands/validation/execution-report.md",".claude/commands/validation/system-review.md",".claude/commands/validation/validate-2.md",".claude/skills/archon-cli/SKILL.md",".claude/skills/archon-cli/authoring/authoring-workflows.md",".claude/skills/archon-cli/authoring/node-reference.md",".claude/skills/archon-cli/authoring/prompting-mistakes.md",".claude/skills/archon-cli/authoring/variables.md",".claude/skills/archon-cli/operate/managing-runs.md",".claude/skills/archon-cli/operate/queues.md",".claude/skills/archon-cli/operate/running.md",".claude/skills/archon-cli/operate/troubleshooting.md",".claude/skills/archon-cli/setup/setup-and-config.md",".claude/skills/docker-extend/SKILL.md",".claude/skills/playwright-cli/SKILL.md",".claude/skills/playwright-cli/references/element-attributes.md",".claude/skills/playwright-cli/references/playwright-tests.md",".claude/skills/playwright-cli/references/request-mocking.md",".claude/skills/playwright-cli/references/running-code.md",".claude/skills/playwright-cli/references/session-management.md",".claude/skills/playwright-cli/references/storage-state.md",".claude/skills/playwright-cli/references/test-generation.md",".claude/skills/playwright-cli/references/tracing.md",".claude/skills/playwright-cli/references/video-recording.md",".claude/skills/release/SKILL.md",".claude/skills/rulecheck/SKILL.md",".claude/skills/rulecheck/rules-guide.md",".claude/skills/rulecheck/workshop-guide.md",".claude/skills/test-release/SKILL.md",".claude/skills/triage/SKILL.md",".claude/skills/triage/workshop-guide.md","AGENTS.md","CLAUDE.md","packages/adapters/src/community/chat/README.md","packages/adapters/src/community/forge/README.md","packages/chat-contract/README.md","packages/docs-web/public/brand/README.md","packages/docs-web/src/content/docs/adapters/community/discord.md","packages/docs-web/src/content/docs/adapters/community/gitea.md","packages/docs-web/src/content/docs/adapters/community/gitlab.md","packages/docs-web/src/content/docs/adapters/github-app-setup.md","packages/docs-web/src/content/docs/adapters/github.md","packages/docs-web/src/content/docs/adapters/index.md","packages/docs-web/src/content/docs/adapters/slack.md","packages/docs-web/src/content/docs/adapters/telegram.md","packages/docs-web/src/content/docs/adapters/web.md","packages/docs-web/src/content/docs/brand/index.md","packages/docs-web/src/content/docs/contributing/cli-internals.md","packages/docs-web/src/content/docs/contributing/dx-quirks.md","packages/docs-web/src/content/docs/contributing/index.md","packages/docs-web/src/content/docs/contributing/new-developer-guide.md","packages/docs-web/src/content/docs/contributing/releasing.md","packages/docs-web/src/content/docs/deployment/cloud.md","packages/docs-web/src/content/docs/deployment/docker.md","packages/docs-web/src/content/docs/deployment/e2e-testing-wsl.md","packages/docs-web/src/content/docs/deployment/e2e-testing.md","packages/docs-web/src/content/docs/deployment/index.md","packages/docs-web/src/content/docs/deployment/local.md","packages/docs-web/src/content/docs/deployment/reverse-proxy.md","packages/docs-web/src/content/docs/deployment/windows.md","packages/docs-web/src/content/docs/getting-started/ai-assistants.md","packages/docs-web/src/content/docs/getting-started/configuration.md","packages/docs-web/src/content/docs/getting-started/first-workflow.md","packages/docs-web/src/content/docs/getting-started/installation.md","packages/docs-web/src/content/docs/getting-started/operate.md","packages/docs-web/src/content/docs/getting-started/quick-start.md","packages/docs-web/src/content/docs/getting-started/sdlc-factory.md","packages/docs-web/src/content/docs/getting-started/updating.md","packages/docs-web/src/content/docs/getting-started/why-archon.md","packages/docs-web/src/content/docs/guides/approval-nodes.md","packages/docs-web/src/content/docs/guides/authoring-commands.md","packages/docs-web/src/content/docs/guides/container-isolation.md","packages/docs-web/src/content/docs/guides/global-workflows.md","packages/docs-web/src/content/docs/guides/hooks.md","packages/docs-web/src/content/docs/guides/index.md","packages/docs-web/src/content/docs/guides/loop-nodes.md","packages/docs-web/src/content/docs/guides/mcp-servers.md","packages/docs-web/src/content/docs/guides/multi-repo-projects.md","packages/docs-web/src/content/docs/guides/proactive-workflows.md","packages/docs-web/src/content/docs/guides/publishing-plugins.md","packages/docs-web/src/content/docs/guides/script-nodes.md","packages/docs-web/src/content/docs/guides/skills.md","packages/docs-web/src/content/docs/guides/workflow-triggers.md","packages/docs-web/src/content/docs/guides/worktrees.md","packages/docs-web/src/content/docs/reference/api.md","packages/docs-web/src/content/docs/reference/architecture.md","packages/docs-web/src/content/docs/reference/archon-directories.md","packages/docs-web/src/content/docs/reference/cli.md","packages/docs-web/src/content/docs/reference/commands.md","packages/docs-web/src/content/docs/reference/configuration.md","packages/docs-web/src/content/docs/reference/database.md","packages/docs-web/src/content/docs/reference/forge.md","packages/docs-web/src/content/docs/reference/index.md","packages/docs-web/src/content/docs/reference/node-execution.md","packages/docs-web/src/content/docs/reference/provider-capabilities.md","packages/docs-web/src/content/docs/reference/sdlc-workflows.md","packages/docs-web/src/content/docs/reference/security.md","packages/docs-web/src/content/docs/reference/troubleshooting.md","packages/docs-web/src/content/docs/reference/variables.md","packages/docs-web/src/content/docs/reference/workflow-language.md","packages/forge/README.md","packages/provider-contract/README.md","packages/providers/src/codex/protocol/README.md","packages/web/src/experiments/console/README.md","packages/web/src/experiments/console/builder/README.md","plugins/chat-slack/archon-plugin.json","plugins/forge-github/archon-plugin.json","plugins/provider-claude/archon-plugin.json","plugins/provider-codex/archon-plugin.json","plugins/provider-pi/archon-plugin.json"],"skills":{".claude/agents/code-reviewer.md":"",".claude/agents/code-simplifier.md":"",".claude/agents/codebase-analyst.md":"",".claude/agents/codebase-explorer.md":"",".claude/agents/comment-analyzer.md":"",".claude/agents/docs-impact.md":"",".claude/agents/pr-test-analyzer.md":"",".claude/agents/rulecheck-agent.md":"",".claude/agents/sdk-verifier.md":"",".claude/agents/silent-failure-hunter.md":"",".claude/agents/triage-agent.md":"",".claude/agents/type-design-analyzer.md":"",".claude/agents/web-researcher.md":"",".claude/commands/commit.md":"",".claude/commands/create-command.md":"",".claude/commands/execute.md":"",".claude/commands/github_bug_fix/implement-fix.md":"",".claude/commands/github_bug_fix/rca.md":"",".claude/commands/handoff.md":"",".claude/commands/plan-feature.md":"",".claude/commands/prime-backend.md":"",".claude/commands/prime-frontend.md":"",".claude/commands/prime-isolation.md":"",".claude/commands/prime-workflows.md":"",".claude/commands/prime.md":"",".claude/commands/review-doc.md":"",".claude/commands/validate.md":"",".claude/commands/validation/code-review-fix.md":"",".claude/commands/validation/code-review.md":"",".claude/commands/validation/execution-report.md":"",".claude/commands/validation/system-review.md":"",".claude/commands/validation/validate-2.md":"",".claude/skills/archon-cli/SKILL.md":"---\nname: archon-cli\ndescription: |\n Drive Archon through its CLI: run AI workflows on a repo, watch and answer the runs\n that need a decision, drive the SDLC pack's queues (intake, build queue, merge queue,\n discoveries), set up Archon or change its config, and author and validate workflows.\n Use when the user says \"use archon\", \"run archon\", \"archon workflow\", \"fix issue #N\n with archon\", \"have archon review this PR\", \"what's running / check run \",\n \"approve/reject/answer/cancel/resume that run\", \"run the build queue\", \"drain\n discoveries\", \"set up archon\", \"configure archon\", \"change my archon config\",\n \"create a workflow\", \"author a workflow\", or asks how to write a better Archon prompt.\n NOT for: doing the coding work yourself. Archon delegates it to isolated runs.\nargument-hint: \"[workflow | run-id | intent]\"\n---\n\n# Archon CLI\n\nArchon runs multi-step AI workflows through the `archon` CLI. Git projects run in\nisolated worktrees by default; registered folder projects run in place. You sit on\ntop of the runs: you write the brief, launch, watch one stream, answer the decisions\nthat reach you, and read what each run left behind.\n\nRoute by intent:\n\n| The user wants to... | Read |\n|---|---|\n| Run a workflow on real work | `operate/running.md` |\n| Inspect, answer, cancel or resume runs | `operate/managing-runs.md` |\n| Drive the SDLC pack's queues | `operate/queues.md` |\n| Find out why a run failed or hangs | `operate/troubleshooting.md` |\n| Set up Archon or change config | `setup/setup-and-config.md` |\n| Author or change a workflow | `authoring/authoring-workflows.md` (then `node-reference.md` and `variables.md` in the same folder) |\n| Improve a node prompt or a run message | `authoring/prompting-mistakes.md` |\n\n- When the intent is clear (\"build me a workflow for X\", \"run archon-ship on issue\n #42\"), go straight to the reference. Do not ask.\n- When it is ambiguous, ask which of these the user wants.\n- On a machine where `archon doctor` fails, start with `setup/setup-and-config.md`.\n\n## The operating loop\n\n1. **Discover.** `archon workflow list --json` gives compact descriptions. For each\n plausible candidate, read the full description with `archon workflow list \n --full`. Choose from full descriptions, never from names you remember.\n2. **Check the brief.** The message, issue body or document the run reads is the\n contract the run is measured against. It must state the problem, why it is worth\n solving, why now, the desired outcome, the invariants and the acceptance. If any\n is missing, say which, propose wording, and get the user's agreement before\n launching. `operate/running.md` has the full check.\n3. **Launch detached.** Pass the work as a message, the workflow's declared inputs\n with `--input`, or both:\n\n ```bash\n archon workflow run --branch \"\" --detach\n archon workflow run --input = --input = --detach\n ```\n\n4. **Watch once.** Run one stream as a background task of your harness, however many\n runs you launched:\n\n ```bash\n archon workflow attention --watch --json # this project; add --all for the install\n ```\n\n Each line is JSON. `attention` means a run needs a decision, `resolved` means it no\n longer does, and `terminal` means a run ended. Act on the line, then keep reading.\n5. **Answer deliberately.** Read the item's question, its recommendation and the\n evidence it links. Answer with a reason, detached:\n `archon workflow respond \"\" --detach`.\n `operate/managing-runs.md` covers every form.\n6. **Read the result.** A completed run is not a verdict. `archon workflow get\n --json` gives the normalized `outcome` and `leave_behind.artifactFiles`.\n Read the report before telling the user what the run concluded.\n\n## Hard rules\n\n- **Never launch on a thin brief.** A weak input does not produce a weak result. It\n produces a confident, well-formed answer to the wrong question, at full price.\n- **Launch and answer with `--detach`.** A detached run starts its own session and\n survives your shell. A foreground `respond` or `resume` continues the run inside\n your shell, and closing the shell stops it.\n- **One watcher, not one per run.** One `workflow attention --watch` stream covers\n every run in scope, including runs that triggers or other sessions start. A\n `workflow wait ` per run is fine for one or two runs; with dozens it\n contends for the database.\n- **Stop work only when you mean to end it.** `archon workflow cancel` stops the run\n mid-node, and that node's provider session and unsaved work are lost. Let a run reach\n its next pause or end when you only want to stop launching more. When one turn is\n stuck on a tool or background command that never finishes, `archon workflow\n end-turn ` ends that turn and keeps the run (`operate/managing-runs.md`,\n \"A stalled turn\").\n- **Merge only what was reviewed.** When you merge a pull request by hand, pin the\n merge to the reviewed head (`gh pr merge --match-head-commit `), read the\n open review threads first, and sync your checkout afterwards.\n- **Author agent-first.** In a workflow you write, an agent node with typed output\n judges, scripts read facts and act at boundaries, and YAML only wires them.\n `authoring/authoring-workflows.md` (\"Agent-first\") has the rule and an example.\n\n## Gotchas\n\n- The current directory selects the project for discovery, launches and project\n listings. `workflow status`, `workflow runs` and `workflow attention` default to\n that project; add `--all` for the whole install. For a git project, run from the\n repo root. Register a non-git folder with `workflow run --folder`. A full run ID\n works from any directory.\n- Attention items are paused runs. A running run stuck on a stalled tool call is\n not an item: `workflow wait ` and `workflow status` show it.\n- `workflow status` and `workflow runs` set `scopeFallback: true` in JSON when an\n unregistered project produced an install-wide result.\n- Prefer `--json` whenever you will parse output.\n- `archon --help` is authoritative. If a flag this skill names is rejected, trust the\n CLI's help and tell the user about the drift.\n",".claude/skills/archon-cli/authoring/authoring-workflows.md":"---\nname: archon-cli-authoring\ndescription: Design and write an Archon workflow: outcome-first decomposition, gate design, node types, loop channels, packaging, fixtures. Read when creating or editing workflow YAML.\n---\n\n# Authoring Workflows\n\nDesign and write an Archon workflow — for code work, business operations, or any\ngoverned process. The method is outcome-first; the mechanics follow from it.\nExemplars: the bundled sdlc pack in any Archon checkout under\n`.archon/workflows/sdlc//` — read a pack YAML before writing your own.\nArchon is not code-only: triage an inbox of tickets, reconcile accounts,\nscreen applicants, keep CRM records honest — the same node types, gates, and\ndiscipline apply. What changes per domain is where the gates come from (below).\n\n## The design sequence\n\nWork through these questions in order, with the user where marked:\n\n1. **Desired outcome.** What artifact or world-state exists when this succeeds?\n One sentence. If it cannot be stated as an outcome, it is not ready to build.\n2. **Specificity (with the user).** Is this workflow written against ONE project\n or outcome, or meant to be generally reusable? This changes everything\n downstream: a project-specific workflow may hardcode that repo's real gates,\n real commands, real rules, and speak in its vocabulary — which makes it far\n more powerful than any generic equivalent. Ask before designing.\n3. **Reuse check.** Which of the USER'S OWN workflows already do part of this?\n (`archon workflow list`, then read their YAML.) Compose those via `include:`.\n\n **The bundled sdlc pack is NOT a component library.** Its workflows exist to\n teach how good workflows are written — read them as worked examples of gate\n placement, prompt contracts, and fixture discipline, never `include:` them\n into a user workflow by default. Their prompts and gates are deliberately\n general so they fit any project; a user workflow composed out of them inherits\n that generality and loses the specificity that made it valuable. If the user\n asks for \"something like archon-ship but for my repo\", write a new workflow in\n their project's terms, using the pack only as the craft reference.\n4. **Primitives.** Thinking in primitives is right: name the small jobs that\n compose into the outcome — investigate, decide, implement, verify, publish;\n or intake, enrich, judge, route, notify for an ops queue.\n Package each coherent reusable primitive as a workflow folder with declared\n `inputs:` and `returns:`. It can then run alone or compose into a parent with\n `include:` and `with:`. Nodes implement a primitive's internals and the small\n one-off glue in a parent: use an AI node for judgment and code for a checkable\n fact. The primitive set comes from THIS outcome, not from copying another\n workflow's node list.\n5. **Gate placement (with the user).** Where must the run stop before\n continuing, and what decides? Three gate kinds, all first-class:\n\n - **Deterministic gates** — a `bash:`/`script:` node owning an exit code or a\n `when:` on a declared field. Use wherever a checkable fact settles it —\n in code work: tests pass, file exists; in ops: totals reconcile, every\n row has an owner, the export count matches the source. Cheapest and least\n arguable.\n - **Prompt command gates** — an independent verifier judging another agent's\n output against an evidence bar. Start the verifier with `context: fresh`,\n have it read the diff/artifact/entry, check claims and criteria, and return a\n structured boolean that drives the loop or branch. When gate design is\n unknown, START HERE: an agent checking agents is the most powerful\n general-purpose gate and catches what no fixed check anticipated. Keep the\n verdict structured (`output_format` boolean) so a machine consumes it; keep\n the judgment prose in the prompt. Grounded on an **authored sidecar** — a\n versioned rubric/directions file in the repo — an agent judgment gate stands\n in for a typical human reviewer: same criteria, same questions, recorded\n answers, every run.\n - **Attention pauses** (`wait: { attention: ..., form: approval }`) — only\n two cases justify them: an **interactive** workflow where someone is present\n at the console and reads each iteration, or a **super load-bearing** action — irreversible,\n public-facing, or expensive beyond easy rollback (deploy, post publicly,\n delete data, send customer-facing communication). Everything else should be\n decidable by code or by another agent. The pause holds the run durably in the\n attention queue, whether it started in the foreground, detached, or from a\n trigger. Container-isolated workflows cannot hold one: Archon refuses a\n workflow with any `wait:` node under container isolation before creating the\n run. Reject is an answer, not a cancel: add a `cancel:` node behind\n `when: \"$.output.decision == 'reject'\"` where rejecting should end the run.\n The older `approval:` node is deprecated.\n\n On a project-specific workflow the user often already knows some of these —\n \"never push before I see the diff\", \"stop if the migration touches billing\",\n \"no applicant advances without both scorecards agreeing\" — collect them\n verbatim; they become attention pauses, cancel nodes, or `when:` conditions.\n Everything else defaults to a prompt command gate until a real run proves\n which part can be made deterministic.\n\n **Gates are latent in every domain.** Any process humans govern already\n invented its controls: double-entry, reconciliation, four-eyes review,\n checklists, read-backs. Elicitation is the authoring work — have a strong\n model propose candidate gates from domain knowledge, then have the user (the\n domain expert) validate which ones actually bind. A proposed gate earns trust\n only after it has demonstrably refused a planted bad outcome — prove gates red\n the way you prove fixtures red.\n6. **Data flow.** What does each node hand the next? Declared values\n (`$node.output`, `output_format` fields, workflow `inputs:`/`returns:`) carry\n JSON values; artifacts (`$ARTIFACTS_DIR`) carry files. The producing node owns\n the schema, including for script results and composed workflows. Read\n `node-reference.md` → Result contracts before declaring a result, and\n `variables.md` → Artifact pointers when returning a file reference.\n7. **Prompting** per node → see `prompting-mistakes.md` in this folder before writing prose.\n8. **Wiring** into YAML (below), then **fixtures**: every authored workflow ships\n a dry-run fixture under `//fixtures/*.stubs.yaml` declaring its\n expected outcome. Prove red paths red before trusting them. Fixtures prove the\n paths that dry-run can execute. A reachable `workflow:` or `include:` +\n `fan_out:` node fails dry-run by design, so prove that path with a small real\n acceptance run while keeping fixtures for the surrounding wiring.\n9. **Validate** before any real run. None of these steps spends on a model:\n\n ```bash\n archon validate workflows # schema, references, command files\n archon workflow run --dry-run --stubs-init stubs.yaml # scratch stub scaffold\n archon workflow run --dry-run --stubs stubs.yaml\n archon workflow test # every declared fixture\n ```\n\n `--stubs-init` writes a block-style YAML stub scaffold to fill in. Keep it outside\n `fixtures/`: a dry-run stub file is not a fixture. A fixture file declares a `fixture:` block, and\n `--stubs` refuses it (\"this is a fixture file; run it with 'workflow test'\"). Copy\n the stub values you need into a fixture and run it with `workflow test`. A dry run\n walks the graph with stubbed node outputs and prints each node's resolved provider\n and model; add `--exec-code` only for trusted `bash:` and `script:` nodes. Then make a planted\n bad case fail: a fixture that never went red proves nothing. Finish with one real\n run on a genuine task.\n\n## Agent-first: who decides what\n\nArchon's rule is **YAML coordinates. Code computes. Agents judge.** Give each kind\nof work to the one that does it well:\n\n- **Agents judge.** Reading a comment, a diff, a ticket or a CI log and deciding what\n it means is a prompt node that returns a small typed result (`output_format`).\n A script that tries the same judgment freezes one guess into code.\n- **Scripts give facts and act at boundaries.** A script reads the forge, git, files\n or the CLI and hands the agent facts, or performs the write the agent decided.\n It never re-judges what the agent already judged. Compute in a `bash:` or\n `script:` node only when the rule is genuinely fixed (parsing JSON, counting,\n comparing heads) or a typed invariant must hold before an irreversible action.\n- **YAML coordinates.** It holds topology, gates on typed fields, joins, sessions and\n waits. Do not grow `when:` into logic; compute the decision in a node and gate on\n its field.\n- **Natural language is not a wire format.** Never regex or keyword-match prose,\n whether a user's message, an agent's output or a vendor's error text, to decide\n what happens next. Let an agent read it and return a typed value.\n\nBad: a script classifies a review comment with a pattern, and the pattern is the\ndecision.\n\n```yaml\n- id: classify\n bash: |\n if printf '%s' \"$COMMENT\" | grep -qiE 'lgtm|approve|ship it'; then echo ready; else echo changes; fi\n- id: merge\n depends_on: [classify]\n when: \"$classify.output == 'ready'\"\n script: merge\n runtime: bun\n```\n\nGood: an agent reads the comment and returns a typed verdict, and the script only\nacts on it.\n\n```yaml\n- id: verdict\n prompt: |\n Read the review comment in $ARTIFACTS_DIR/comment.md. Decide whether the\n reviewer approves merging this change as it stands.\n output_format:\n type: object\n properties:\n ready: { type: boolean }\n reason: { type: string }\n required: [ready, reason]\n- id: merge\n depends_on: [verdict]\n when: \"$verdict.output.ready == true\"\n script: merge\n runtime: bun\n```\n\nTest at the same seams. A script gets a test at its tool boundary: it writes an issue\nonce, reads back a pushed head, merges only what was approved. Agent judgment is\nchecked by outcome, through dry-run fixtures (`archon workflow test`) and real runs,\nnever by a test that pins a prompt's wording, the YAML's shape or the route a run\ntakes. Do not retest what the engine owns (`when:`, includes, loops, output\nvalidation). In an Archon checkout, `.archon/workflow-language-constitution.md` and\n`.archon/workflows/sdlc/CONSTITUTION.md` (sections 1 to 5 and 13) state these rules\nin full.\n\n## Start simple, then adapt to what runs teach\n\nThe first version is deliberately under-engineered:\n\n- Use few nodes, short prompts, and key gates. Do not add determinism without evidence;\n before a real run, it is only a guess about where things fail.\n- Dogfood it immediately on something real — a genuine task in the actual repo,\n not a demo. The run itself is the test.\n- Adapt from evidence, not anticipation: a failure shows which gate was missing;\n a wasted review shows which check earned its place. Add machinery only where a\n logged occurrence demands it.\n- Iterate in place: edit the folder, rerun the same kind of task, compare the\n artifacts. The workflow converges on the project instead of being designed\n up front.\n\nAll mechanical detail lives in `node-reference.md` (every node type and field,\nwhen:/trigger_rule wiring, fixtures) with the full substitution semantics in\n`variables.md` — read both when writing YAML.\n\n## File layout — one folder per workflow\n\nKeep each workflow in its own folder. If its scripts use pack-level shared\nmodules, copy the pack when moving it between repos. To start a workflow:\n\n```bash\nmkdir -p .archon/workflows/my-pack/my-workflow/{commands,scripts,fixtures}\n```\n\n```text\n.archon/workflows///\n├── .yaml # name, description, inputs:, returns:, nodes:\n├── commands/*.md # prompt files referenced by command: nodes\n├── scripts/*.py|.ts # deterministic logic (Python/uv preferred, TS/bun fine)\n└── fixtures/*.stubs.yaml\n```\n\nSubstantive prompts live in command files, not inline. Inline `bash:` only for\none-or-two-line glue; anything with branching is a script file. Never shell as a\nscript language for logic. Ask the user their script-language preference if they\nwill maintain it. Declare Python dependencies inline (`deps:` for `uv`); keep\n`node_modules` and virtual environments out of the packaged script tree.\n\nPut shared `.ts`, `.js`, or `.py` modules and `.md` documents in\n`/.shared/` (subfolders are supported). This reserved directory supplies\nmodules and documents, never workflow definitions or `script:` targets. Documents\nship beside the modules in every build, so a script finds one relative to its own\nlocation and hands its path to a prompt node through `with:`. Missing packaged script targets fail at load time. From `/scripts/publish.ts`, Bun can import\n`../../.shared/result.ts`. Python files can add\n`str(Path(__file__).resolve().parents[2] / \".shared\")` to `sys.path` using\n`pathlib.Path`, then import normally; Archon does not inject `PYTHONPATH`.\nAdjust the relative depth for grouped scripts.\n\nThe same paths work in project/global source, bundled binaries, and frozen\ncaptures. Keep imports inside the pack and require no npm packages or target\nproject configuration. Use regular module files: the binary generator rejects\nsymlinks under `.shared`. Write outputs to `ARTIFACTS_DIR` or `STATE_DIR`, never\nbeside a script; Python bytecode caching is disabled in runs and executable fixtures.\n\n## Node types — one per node\n\n`command` (prompt file) · `prompt` (inline) · `bash` (shell, no AI) · `script`\n(py/ts, no AI) · `loop` (iterate one AI node) · `loop_group` (repeat a sub-DAG) ·\n`approval` (deprecated; use `wait: attention`) · `cancel` (terminate with reason, usually behind `when:`) ·\n`wait` (durable suspension, or an `attention:` question answered in a form) · `workflow` (governed child run) · `include`\n(plain load-time composition or runtime-width in-run composition with `fan_out:`).\n\nSelection rules of thumb:\n\n- A machine-verifiable check → `bash:`/`script:` node, never an AI asked to \"check\".\n- Model judgment that gates downstream spend → AI node with `output_format` boolean\n + a downstream gate or loop channel reading that field.\n- Repeated act→verify cycle → `loop_group` with the verify node's structured\n boolean driving completion.\n\n## Loop completion channels — pick by tier\n\n- Completion externally checkable → `until_bash: \"\"`.\n- Completion is the model's judgment → `output_format` + `until_field: `.\n- Prose sentinel (`until: TOKEN`) is deprecated; prefer the channels above.\n Declare at least one channel per loop.\n\n## Structured output: only where a machine decides\n\nDeclare `output_format` when a `when:`, `until_field`, or script consumes the\nfield. Otherwise let output stay whole-string prose — schemas are a reliability\ntax on non-enforcing providers. Provider-agnostic YAML always: tiers\n(`small|medium|large`) never literal model ids, no `provider:` keys in bundled work.\n\n## Isolation and interactivity\n\n- At workflow level, `worktree.enabled: true` pins worktree isolation. Omission\n leaves the choice to the caller. On a `workflow:` child node,\n `isolation: worktree` explicitly gives the child its own worktree. A worktree\n bounds git files; it does NOT isolate `~/.archon`, env, database, or sessions.\n- A `wait: attention` node pauses the run in the attention queue until it is answered. It\n needs no workflow-level declaration and does not stop a detached or triggered launch.\n- Composition (`include:`) runs inside the parent's single run/isolation/audit\n trail. Use `workflow:` sub-runs only when a separately governed launch is the\n actual requirement.\n\n## Common mistakes\n\nRead before writing YAML:\n\n- **Prose between nodes as a wire format.** Emitting a token so the next node can\n grep it. Fix: structured output + typed reads, or a script exit code.\n- **AI doing what code should.** \"Check if tests pass\" as a prompt. Fix: bash/script\n node owning the exit code.\n- **Parsing model prose to decide.** Regex over `$node.output`. Same fix.\n- **Hardcoding the project's toolchain** (`tsc`, `pytest`) in default-workflow\n gates. Deterministic checks verify only what Archon owns (git state, artifacts,\n exit codes of agent-discovered commands).\n- **Silent fallbacks.** An optional input that degrades quietly instead of failing.\n Fail loud with the missing thing named.\n- **Trusting exit codes / run status as verdicts.** A declined task exits 0;\n gate on artifacts existing and validating, and on declared outcome fields.\n- **Skipping fixtures.** Unfalsified wiring is unknown wiring. Expected-red paths\n especially: seen red, or they prove nothing.\n- **Inline everything.** Long prompts inline in YAML, logic inline in bash.\n Files age better, diff better, and are reusable across nodes.\n",".claude/skills/archon-cli/authoring/node-reference.md":"# Node Reference\n\nMechanical reference: every node type, its fields, how nodes wire together, and\nhow to prove wiring with fixtures. For design judgment (gates, primitives,\nprompting) read `authoring-workflows.md` in this folder first.\n\n## Workflow-level fields\n\n```yaml\nname: my-workflow # unique; user workflows may shadow bundled names\ndescription: |\n What this does and when to use it. Shown by `archon workflow list`.\nmodel: large # tier keyword (small|medium|large) or @alias — never a literal model id\ninputs: # declared signature; callers pass via --input name=value\n work:\n default: \"\"\n description: Optional work override; prompts read $ARGUMENTS explicitly for fallback\nreturns: implement # which node's output is the workflow's terminal output\noutcome_field: green # persist one authored boolean beside run status (e.g. green/ready/rooted)\nworktree:\n enabled: true # pin worktree isolation. Bounds git files ONLY —\n # not ~/.archon, env vars, database, or sessions\nmutates_checkout: false # declare when the workflow never touches the working tree\n```\n\nAn input default does not fall back to the invocation message automatically.\nWhen both are valid sources, give the model both values and state the precedence:\n\n```yaml\n- id: implement\n prompt: |\n Optional work override: $INPUTS.work\n Original invocation: $ARGUMENTS\n Use the work override when it is non-empty; otherwise use the original invocation.\n```\n\n## The eleven node types\n\nExactly one of these appears per node: `command`, `prompt`, `bash`, `script`,\n`loop`, `loop_group`, `approval`, `cancel`, `wait`, `workflow`, `include`.\n`approval` is deprecated; new pauses use `wait: { attention: ..., form: ... }`.\n\n### command / prompt — AI nodes\n\n```yaml\n- id: plan\n command: plan # loads /commands/plan.md — prefer files over inline prose\n depends_on: [investigate]\n```\n```yaml\n- id: classify\n prompt: \"Classify $ARGUMENTS. Set type to BUG or FEATURE.\"\n allowed_tools: [] # no tools needed for pure judgment\n output_format: # declare ONLY when a machine consumes a field (gate/until_field/script)\n type: object\n properties:\n type: { type: string, enum: [BUG, FEATURE] }\n required: [type]\n```\n\nKey fields on AI nodes: `model`/`provider` (tiers), `output_format` (+ `output_type`\nfor typed artifact sidecars), `allowed_tools`/`denied_tools`, `effort`/`thinking`,\n`retry` (default 2x on transient), `persist_session` (continues across runs only on a\nprovider that supports session forks; others start fresh each run), `idle_timeout`.\n\nSession context is explicit when it matters:\n\n- Omitted context inherits the prior compatible provider session in a sequential\n layer and starts fresh in a parallel layer.\n- `context: fresh` always starts clean. Use it for independent verification.\n- `context: shared` explicitly inherits the ambient session in a sequential\n layer. It is invalid where parallel structure makes that ancestry ambiguous.\n- `context: { resume: plan }` forks the named completed upstream node's session.\n Use it when one exact ancestry matters; the provider must support session forks.\n Inside a `loop_group` body the source can be an enclosing node, whose session the\n body continues across iterations, or an upstream node in the same body, whose\n session of that iteration the consumer forks. The same-body form suits a follow-up that asks the agent to\n finish a step it skipped.\n\n### bash — deterministic shell, no AI\n\n```yaml\n- id: test-gate\n bash: bun run test\n timeout: 300000 # ms; stdout captured as $test-gate.output\n```\nExit code decides pass/fail. On `timeout`, Archon signals a host node's process tree,\nso work behind `bun run` or another wrapper stops too. A process that leaves the node's\nprocess group (`setsid`) escapes. In a container node, a timeout ends only the local\n`docker exec` client, and the command inside the container may keep running. In a detached run on macOS or Linux, a timeout whose\ncleanup cannot be confirmed fails the node, even with `on_timeout: skip`.\n\nThe same node shape verifies non-code work:\n`bash: python3 scripts/reconcile.py --period 2026-08` (totals must balance),\nor a script that checks every imported row has an owner. One-or-two-line glue\nonly; anything with branching is a script node.\n\n### script — TypeScript (bun) or Python (uv), no AI\n\n```yaml\n- id: verify-report\n script: verify-report # loads /scripts/verify-report.py\n runtime: uv\n depends_on: [implement, review]\n with: # typed value transport into INPUTS_ env vars\n green: \"$implement.output.green\"\n prior: {from: \"$review.output\", if_skipped: \"none\"}\n```\n\nPrefer named script files over inline bodies. Python (`runtime: uv`) preferred,\nTypeScript (`runtime: bun`) fine. `deps:` adds uv dependencies.\n\n### Result contracts — the producer owns the schema\n\nUse the producing node's `output_format` for a JSON result. `returns:` selects\nthat node; it does not declare another schema. No value-shape declaration belongs\non `inputs:` or `returns:`.\n\n```yaml\nname: certified-result\ndescription: Certify a deterministic result and bind its field downstream\nreturns: build\nnodes:\n - id: build\n bash: printf '%s' '{\"ready\":true}'\n output_format:\n type: object\n properties:\n ready: {type: boolean}\n required: [ready]\n - id: consume\n depends_on: [build]\n with:\n ready: \"$build.output.ready\"\n runtime: uv\n script: |\n import os\n print(os.environ[\"INPUTS_READY\"])\n```\n\nA `bash:` or `script:` node with `output_format` must print one strict JSON\ndocument satisfying that schema. Send diagnostics to stderr. There is no JSON\nrepair or reask; a contract violation fails the node and is not retried, even\nwith `retry:`. A schema that cannot compile is a load error. Without\n`output_format`, exec stdout remains raw text. Named scripts use the same rule;\nthe small bash example above keeps the handoff visible.\n\nAn `include:` alias exposes the selected producer's contract through flattening.\nA `workflow:` caller receives the child's selected result and declared field\nnames, persisted for cold resume. Do not repeat the schema on the caller:\n`output_format` on a `workflow:` node is a load error; on `include:` it is ignored\nwith a warning. A schemaless child stays schemaless. Fan-out returns an ordered\narray of item values; consume the whole aggregate, not a field on the array.\n\nFor field-access and file-pointer rules, read `variables.md` → Node Output Details and\nArtifact pointers. The docs' `reference/workflow-language.md` → Result contracts\ngives the full composition examples.\n\n### loop — iterate ONE AI job\n\n```yaml\n- id: implement\n loop:\n command: implement\n until_field: done # boolean in this node's output_format\n max_iterations: 5\n depends_on: [plan]\n output_format:\n type: object\n properties:\n done: {type: boolean}\n required: [done]\n```\n\nCompletion channels — declare at least one, pick by tier:\n\n- `until_bash: \"\"` — completion externally checkable (deterministic)\n- `until_field: ` — completion is the model's judgment, via `output_format`\n- `until: TOKEN` — deprecated prose sentinel; use one of the channels above\n\nAlso: `fresh_context: true` (each iteration starts clean) and `$LOOP_PREV_OUTPUT`\nfor previous-iteration state.\nA failed iteration fails the loop at `max_iterations` — bound exhaustion fails\ntruthfully rather than blessing a bad last attempt.\n\n### loop_group — repeat a sub-DAG\n\n```yaml\n- id: fix-cycle\n depends_on: [review-findings]\n loop_group:\n nodes:\n - id: fix\n prompt: \"Address findings: $review-findings.output\"\n - id: recheck\n prompt: \"Verify each finding is fixed with evidence.\"\n depends_on: [fix]\n context: fresh\n output_format: {type: object, properties: {ready: {type: boolean}}, required: [ready]}\n until_bash: 'ready=$recheck.output.ready; test \"$ready\" = \"true\"'\n max_iterations: 5\n```\n\nBody is sealed (no external `depends_on`); outer outputs reach bodies via\n`$nodeId.output`. In a `loop_group` body, `$LOOP_PREV..output` reads the\nprevious iteration: prompts text-substitute it, while `when:` conditions resolve it\nas a typed condition reference. A failed body node fails the group immediately.\n\n### approval — deprecated\n\n`approval:` still loads and runs, but the loader warns once per workflow file, naming\neach node and its replacement. Do not write new ones. Replace:\n\n- `approval: { message }` → `wait: { attention: , form: approval }`. A legacy\n reject cancels the run; the attention form continues with `{decision: 'reject'}`, so\n add a `cancel:` node with `when: \"$.output.decision == 'reject'\"` where rejecting\n should end the run.\n- `approval.decisions` → `wait: { attention, form: select, options }` with the same ids\n and labels; same `{decision, text}` output.\n- `capture_response` → read the answer's `$.output.text`; every form records text.\n- `on_reject` / `$REJECTION_REASON` → a rework node with\n `when: \"$.output.decision == 'reject'\"` that reads `$.output.text`, inside a\n `loop_group` if it should repeat.\n\n### cancel — terminate deliberately\n\n```yaml\n- id: refuse\n cancel: \"This workflow handles bugs only.\"\n when: \"$classify.output.type != 'BUG'\"\n```\n\n### workflow / include — reuse another workflow\n\nUse `workflow:` to start a governed child run with its own artifacts, gates, cost,\nand audit trail. Use `include:` to flatten a reusable workflow block into the\ncurrent run at load time.\n\n```yaml\n- id: review-child\n workflow: archon-review\n with:\n scope: \"$INPUTS.branch\"\n isolation: worktree\n\n- id: review-inline\n include: archon-review\n with:\n scope: \"$INPUTS.branch\"\n```\n\nThe `workflow:` target name is static YAML but resolves when the node executes,\nso a prior node may author the child workflow. `workflow:` also accepts `input:`\ninstead of `with:` and can declare `fan_out:`. A plain `include:` resolves and\nexpands fully at load time; the directive carries only structural graph fields\nplus `with:` and has no execution surface of its own. The include's `when:` gates the\nwhole block. Inside a `loop_group` it reads `$LOOP_PREV` from the loop that contains\nthe include.\n\nOn a `workflow:` node, `fan_out.max_parallel` limits unfinished children (default\n`5`). `max_parallel: all` starts every item at once: use it when each child asks an\nindependent attention question, because a paused child keeps its slot and a numeric\nwindow leaves later questions unstarted. Under `join: all_done` the node completes once\nevery child is terminal, even when some failed, never started or were cancelled; the run\nrecords each slot's outcome for operators (`workflow get`), but a downstream node that\njudges the results reads the `archon_failed` markers in `$.output`.\n\nPut `fan_out:` on `include:` when runtime data determines how many copies of a\nstatic block should run inside the parent run:\n\n```yaml\n- id: list-scopes\n bash: printf '[\"packages/cli\",\"packages/workflows\"]'\n\n- id: review-each\n include: archon-review\n depends_on: [list-scopes]\n fan_out:\n items: \"$list-scopes.output\"\n as: scope # required; each instance receives $INPUTS.scope\n max_parallel: 1 # serial escape when the included block may write\n join: all_done\n```\n\nThis form creates no child runs. It returns an item-ordered JSON array under\n`$review-each.output`. With `join: all_done`, a failed instance contributes an\n`archon_failed` marker; `all_success` fails the node. To run instances\nconcurrently, the complete included block must declare `mutates_checkout: false`.\nApproval gates, durable waits, and other suspension paths are not supported\ninside composed fan-out; put them before or after the fan-out.\n\n### wait — suspend durably\n\n```yaml\n- id: pause-for-ci\n wait:\n duration_ms: 300000\n```\n\nA wait declares exactly one condition: `duration_ms`, an ISO timestamp under\n`until`, `event` plus `deadline_ms`, or `attention`. Archon persists the suspension and\nreleases the worker slot. A time or event wait's fixed structured output includes\n`status` (`satisfied` or `expired`) and `waited_ms`; event waits may also return `event`\nand `payload`.\n\n`attention` asks a question that pauses the run until someone answers it in its `form`:\n\n```yaml\n- id: ask\n depends_on: [plan]\n wait:\n attention: \"$plan.output.question\"\n form: select # message (default) | approval | select | multi_select\n options: # select and multi_select only; or one whole \"$plan.output.options\"\n - { id: use-main, label: \"Base on main\" }\n - { id: use-dev }\n labels: # optional; plain strings, runtime refs resolved at pause\n about: \"$plan.output.topic\"\n```\n\nThe next node reads the answer: `{text}` for `message`, `{decision, text}` for `approval`\nand `select`, `{decisions, text}` for `multi_select`. In the `approval` form `reject` is\nan answer and never cancels the run; branch on `$ask.output.decision` with `when:`:\n\n```yaml\n- id: review\n depends_on: [plan]\n wait:\n attention: \"Approve this plan? $plan.output\"\n form: approval\n- id: stop\n depends_on: [review]\n when: \"$review.output.decision == 'reject'\"\n cancel: \"Plan rejected.\"\n- id: implement\n depends_on: [review]\n when: \"$review.output.decision == 'approve'\"\n command: implement\n```\n\nPause only for an interactive session or a super load-bearing action. The run pauses\nin the attention queue until answered, however it was started. To ask after each pass\nof a repeated body, end a `loop_group` body in the wait (it must be the body's sole\nterminal sink) and read the answer next iteration as `$LOOP_PREV..output.text`.\n\n`labels` mean nothing to the engine; they let the user's handler workflows pick the\npause out of `archon workflow attention --label k=v`.\n\n## Wiring nodes together\n\n**`depends_on`** creates edges; independent nodes in one topological layer run\nconcurrently.\n\n**Data flow** — declared values carry scalars, artifacts carry documents:\n\n- `$nodeId.output` — whole text of an upstream node; unknown/skipped producer → `''`\n- `$nodeId.output.field` — strict JSON access: missing key **fails the consumer**\n (never silent-empty); declared-optional field resolves to `''`\n- `with:` bindings (#2637) — prompt/command files read bound values as\n `$INPUTS.`; bash/script processes receive `INPUTS_` env vars.\n `{from, if_skipped}` discriminates skipped producers from ran ones; a failed\n producer fails the binding\n- `$INPUTS.` — declared workflow inputs, also delivered as\n `INPUTS_` to bash/script\n- `$ARTIFACTS_DIR` — pre-created directory for reports/evidence humans read.\n Throwaway checkouts and dependency installs go under `$ARTIFACTS_DIR/.archon/scratch/`\n (create it with `mkdir -p`), which Archon deletes once the run ends and its nodes have\n stopped (a container run's when its container is removed); the rest of\n `$ARTIFACTS_DIR` is kept\n- In `bash:` and `script:` sources, user-controlled variables (`$ARGUMENTS`,\n `$USER_MESSAGE`, `$LOOP_USER_INPUT`, `$LOOP_PREV_OUTPUT`, `$REJECTION_REASON`,\n `$CONTEXT`) are **not** spliced as raw text (injection guard); they arrive as\n environment variables (`ARGUMENTS`, `USER_MESSAGE`, `LOOP_USER_INPUT`,\n `LOOP_PREV_OUTPUT`, `REJECTION_REASON`, `CONTEXT`, `EXTERNAL_CONTEXT`,\n `ISSUE_CONTEXT`). Read an environment-delivered value in `bash:` as `\"$ARGUMENTS\"`.\n In `script:` read it via `process.env.ARGUMENTS` (bun) or `os.environ['ARGUMENTS']`\n (uv/python).\n A `loop_group` body's `bash:` node is the exception: the loop scope splices the\n reply (`$LOOP_USER_INPUT`) into its source, shell-quoted, so the reply arrives\n already quoted. Read the spliced reply as an already-quoted value — assign it\n and quote the variable (`value=$LOOP_USER_INPUT; printf '%s' \"$value\"`) — rather\n than as `\"$LOOP_USER_INPUT\"`.\n `$nodeId.output` refs ARE substituted; give prose producers an `output_format`\n before assigning their output directly in a script.\n\n**`when:` conditions** skip a node when false (skipped propagates to dependants):\n\n```yaml\nwhen: \"$classify.output.type == 'BUG'\"\nwhen: \"$score.output.confidence >= '0.9' && $gate.output.proceed == true\"\n```\n\nOperators: `==`, `!=`, `<`, `>`, `<=`, `>=` (numbers auto-parse, fail-closed on\nnon-numeric), compound with `&&`/`||` (`&&` binds tighter, no parentheses).\nMalformed expression → node skipped + warning. Dot-access contract violation →\nnode FAILS loudly. Guard optional paths with `when:` or `trigger_rule`.\n\n**`trigger_rule`** — join semantics over dependencies:\n\n| Value | Behavior |\n|-------|----------|\n| `all_success` | all deps succeeded (default) |\n| `one_success` | at least one dep succeeded |\n| `none_failed_min_one_success` | none failed AND ≥1 succeeded (skips OK) |\n| `all_done` | all deps terminal (completed, failed, OR skipped) |\n\n## Fixtures — prove wiring without AI spend\n\nEvery authored workflow ships dry-run fixtures in\n`/fixtures/.stubs.yaml`:\n\n```yaml\n# Declared expectations + node stubs. Every non-reserved key is a node output.\nfixture:\n expect: completed # or failed / paused / cancelled\n fail-node: assert-changed # required when expect: failed — must match exactly\n inputs:\n branch: task-42\nimplement:\n done: true\n green: true\n summary: \"stub summary\"\nexec-code: false # true executes bash/script nodes for real (requires a git checkout)\n```\n\nRun them:\n\n```bash\narchon workflow test # everything discovered\narchon workflow test my-workflow # one workflow's fixtures\n```\n\nA reachable attention wait pauses the simulation unless the fixture stubs it; the stub\nstands in for the answer and must match the form's output, e.g.\n`review: { decision: approve, text: \"\" }`. Deprecated `approval:` gates auto-approve.\n\nExpected-red fixtures are the important ones: a guard that has never been seen\nfailing proves nothing. Prove reds red before trusting them. `workflow test`\nmirrors what a real run does with its two directories: named scripts and command\nfiles come from one frozen capture of your working tree taken per invocation —\nuncommitted edits included, so authoring works as normal — while exec-code nodes\nexecute against a scratch worktree of HEAD. So a script that reaches outside\n`.archon/` with a `__file__`-relative path fails the fixture exactly as it would\nfail the run, and nothing a node executes can touch your checkout. Exec-code\nfixtures require a git checkout and fail explicitly outside one. Validate\nload-time errors with `archon workflow list`.\n",".claude/skills/archon-cli/authoring/prompting-mistakes.md":"---\nname: archon-cli-prompting-mistakes\ndescription: Common prompt mistakes when invoking Archon workflows or writing node prompts. Short, negative-form guidance. Read before dispatching work or authoring prompts.\n---\n\n# Prompting Basics\n\n## General\n\n1. Agents are smart — take advantage of that. Each command node runs a real\n coding-agent harness under the hood, with all its capabilities.\n2. Agents inside Archon do not necessarily know about Archon itself, this run,\n or past failures. Do not reference context the agent has no awareness of.\n\n# Prompting Mistakes\n\nShort list. Applies in two places: the **message you pass when invoking a\nworkflow** (it becomes `$ARGUMENTS` for the whole run) and the **prompts inside\ncommand/prompt nodes** you author.\n\n## The mistakes\n\n1. **Vague outcome, implied method.** \"Look into the auth thing.\" Say what done\n looks like and where context lives: \"Fix issue #42. Use the issue, comments,\n and current source as evidence. Preserve the documented login behavior.\"\n2. **Smuggling your diagnosis.** If you want the run's investigation tested,\n ask for the fix in ordinary language — do not hand it your suspected root\n cause as fact unless you have proven it.\n3. **Narrating to nobody.** Unattended nodes produce artifacts, commits, and\n declared fields — not chat. Prompts that say \"report to me below\" produce\n output nothing ever reads. Point every instruction at the artifact it serves.\n4. **No evidence bar.** A judging prompt without \"cite the causal line / drop\n anything that rests on 'might'\" collects plausible filler. State what counts\n as proof, and demand silence otherwise.\n5. **Trusting exit codes as verdicts.** A declined task exits 0. Gates read\n artifacts and declared fields, not success bits.\n6. **Prose wire formats.** Asking a node to end with a magic token the next node\n greps. Use structured output fields or script exit codes instead.\n7. **Everything-but-the-kitchen-sink scope.** One node, one job, stated non-goals.\n \"Also update docs and tests and the changelog\" dilutes all three. Negative\n scope (\"do not touch the lockfile\") is as load-bearing as positive.\n8. **Assuming memory.** Each node may be a fresh session with no prior context.\n Restate the input path, artifact path, and constraint inside each prompt.\n9. **Stop rules left unstated.** Tell the agent when to stop and surface:\n ambiguity → present options; missing context → name it. Never \"use judgment\"\n on decisions with real cost.\n10. **Soft failure language.** \"Try to...\" invites theater. Put checkable failure\n in a `bash:`/`script:` node whose exit code fails the run, or have a judging\n node return a structured boolean and gate on it deterministically.\n\n## The one-line test\n\nBefore sending any prompt — invocation or node — ask: *could a competent engineer\nwho has never seen this conversation act on exactly this text?* If the answer\nneeds context that lives only in your head, the prompt is not done.\n",".claude/skills/archon-cli/authoring/variables.md":"# Variable Substitution Reference\n\nVariables are placeholders in command files and workflow prompts that get replaced at execution time.\n\n## Variable Table\n\n| Variable | Scope | Description |\n|----------|-------|-------------|\n| `$ARGUMENTS` | All modes | The user's original message passed to the workflow |\n| `$USER_MESSAGE` | All modes | Same as `$ARGUMENTS` — both resolve to the user's message |\n| `$WORKFLOW_ID` | All modes | Unique workflow run ID (for tracking and logging) |\n| `$ARTIFACTS_DIR` | All modes | Pre-created directory for this workflow run's artifacts. Write outputs here. Scratch work (a throwaway checkout, a dependency install) goes under `$ARTIFACTS_DIR/.archon/scratch/`, which Archon deletes once the run ends and its nodes have stopped (a container run's when its container is removed) |\n| `$BASE_BRANCH` | All modes | The run's resolved or recorded base branch. Throws if referenced but unresolved. See the [Variable Reference](https://archon.diy/reference/variables/#workflow-variables) for resolution and child inheritance rules |\n| `$DOCS_DIR` | All modes | Documentation directory (config `docs.path`, default `docs/`). Never throws |\n| `$CONTEXT` | All modes | GitHub issue/PR context (if available from platform). Empty string if unavailable |\n| `$EXTERNAL_CONTEXT` | All modes | Alias for `$CONTEXT` |\n| `$ISSUE_CONTEXT` | All modes | Alias for `$CONTEXT` |\n| `$LOOP_USER_INPUT` | Loop / loop_group prompts | **Deprecated** with interactive loop gates; new loops end a `loop_group` body in a `wait: attention` node and read `$LOOP_PREV..output.text`. Feedback from `/workflow approve ` at an interactive loop gate. Populated ONLY on the first iteration after a resume; empty string everywhere else |\n| `$LOOP_PREV_OUTPUT` | Loop prompts | Previous iteration's cleaned output (completion tags stripped). Empty on iteration 1. Key tool for `fresh_context: true` loops that need to know what the last pass did |\n| `$LOOP_PREV..output[.field]` | loop_group body prompts and `when:` conditions | Previous iteration's output of a specific body node. Empty on iteration 1. Field access follows the strict contract below (except genuinely-absent prior output → `''`). In a body `when:`, it is a typed condition reference rather than text substitution |\n| `$REJECTION_REASON` | Legacy `approval.on_reject` prompts | **Deprecated.** The reason from `/workflow reject `. Empty string everywhere else. New workflows read an attention wait's `$.output.text` from a node behind `when: \"$.output.decision == 'reject'\"` |\n| `$nodeId.output` | DAG only | Full text output of a completed upstream node. Unknown/skipped producer → `''` |\n| `$nodeId.output.field` | DAG only | JSON field access — **strict**: an unresolvable field FAILS the consuming node (see below) |\n\n## Where Variables Are Substituted\n\n- **Command files** (`.archon/commands/*.md`) — the core set (`$ARGUMENTS`/`$USER_MESSAGE`, `$WORKFLOW_ID`, `$ARTIFACTS_DIR`, `$BASE_BRANCH`, `$DOCS_DIR`, `$CONTEXT` family), plus `$nodeId.output[.field]` when the command runs as a DAG node. A command file referenced by `loop.command` or a `loop_group` body receives the same populated loop variables as an inline loop prompt. Ordinary DAG command nodes receive `''` for loop/rejection variables. `$REJECTION_REASON` is populated only in an `approval.on_reject` prompt\n- **Inline `prompt:` fields** — in DAG prompt nodes, loop prompts, and loop_group body prompts\n- **`bash:` scripts** — SPECIAL: user-controlled variables (`$ARGUMENTS`, `$USER_MESSAGE`, `$LOOP_USER_INPUT`, `$LOOP_PREV_OUTPUT`, `$REJECTION_REASON`, `$CONTEXT`) are **NOT spliced as raw text** into the script (shell-injection guard). A `loop_group` body's `bash:` node is the exception: the loop scope splices the reply (`$LOOP_USER_INPUT`) into its source, shell-quoted, so the reply arrives already quoted. Read the spliced reply as an already-quoted value — assign it and quote the variable (`value=$LOOP_USER_INPUT; printf '%s' \"$value\"`) — rather than as `\"$LOOP_USER_INPUT\"`. In `bash:`, they arrive as **environment variables** instead: `ARGUMENTS`, `USER_MESSAGE`, `LOOP_USER_INPUT`, `LOOP_PREV_OUTPUT`, `REJECTION_REASON`, `CONTEXT` (+ `EXTERNAL_CONTEXT`/`ISSUE_CONTEXT`), plus `ARTIFACTS_DIR`, `LOG_DIR`, `BASE_BRANCH` — read an environment-delivered value with `\"$ARGUMENTS\"` as normal shell env access. `$nodeId.output` refs ARE substituted: small string values are single-quoted inline; values exceeding 32,768 UTF-16 code units (JavaScript `string.length`) spill to a file and substitute as unquoted `$(cat '')`, which drops trailing newlines; the command substitution splits words and expands globs when used as a bare argument. Assign first (`value=$nodeId.output`), then quote the shell variable (`printf '%s' \"$value\"`) to handle both forms. See [Shell quoting guidance](https://archon.diy/reference/variables/#shell-quoting-in-bash-vs-script).\n- **`script:` bodies** — like `bash:`, user-controlled variables (`$ARGUMENTS`, `$USER_MESSAGE`, `$LOOP_USER_INPUT`, `$LOOP_PREV_OUTPUT`, `$REJECTION_REASON`, `$CONTEXT`) are **NOT spliced as raw text** into the source (injection guard, #2115). They arrive as **environment variables** — `ARGUMENTS`, `USER_MESSAGE`, `LOOP_USER_INPUT`, `LOOP_PREV_OUTPUT`, `REJECTION_REASON`, `CONTEXT` (+ `EXTERNAL_CONTEXT`/`ISSUE_CONTEXT`), plus `ARTIFACTS_DIR`, `LOG_DIR`, `BASE_BRANCH` and managed per-project env — read via `process.env.ARGUMENTS` (bun) / `os.environ['ARGUMENTS']` (uv/python) — env vars are the general injection-safe channel for untrusted values. A literal `$ARGUMENTS`/`$USER_MESSAGE`/`$CONTEXT` left in the source is not substituted: the text stays in the source. `$nodeId.output` values are still substituted **raw** (not shell-quoted). Direct assignment (`const data = $nodeId.output;`) is safe **only with `runtime: bun` when the producer uses `output_format`**. JSON booleans and nulls are not Python literals, so a `runtime: uv` script should bind the value with `with: { data: \"$nodeId.output\" }` and parse `os.environ['INPUTS_DATA']` with `json.loads`. For arbitrary-text producers (bash/script stdout or prose), use the same environment binding instead of embedding the raw value in source, then parse defensively only if the text is expected to contain JSON. **Avoid wrapping `$nodeId.output` in a `String.raw` template literal** — it silently breaks when the output contains a backtick (common in AI-generated markdown and `output_format` payloads)\n\n## Substitution Order\n\nA template is substituted in one pass. Each reference written in the template resolves once, and the value is inserted exactly as written: a message, issue context, loop reply, rejection reason, previous output, or input value that contains `$nodeId.output`, `$INPUTS.`, a variable name, or `$&` reaches the node unchanged. Where two grammars match at the same `$`, the earlier group wins:\n\n1. Loop references inside a `loop_group` body (`$LOOP_PREV..output`, the group's `$LOOP_USER_INPUT`)\n2. Workflow variables (`$WORKFLOW_ID`, `$ARGUMENTS`, `$ARTIFACTS_DIR`, `$BASE_BRANCH`, `$DOCS_DIR`, `$INPUTS.`, `$CONTEXT`, loop/rejection vars)\n3. Node output references (`$nodeId.output`, `$nodeId.output.field`) — DAG mode only\n\n## Context Auto-Append\n\nIf `$CONTEXT` / `$EXTERNAL_CONTEXT` / `$ISSUE_CONTEXT` is NOT present anywhere in the prompt template but context exists (e.g., from a GitHub issue), it is automatically appended at the end after a `---` separator.\n\n## NOT Supported: `$1` … `$9` Positional Arguments\n\nDespite older docs suggesting otherwise, positional `$1`…`$9` are **not substituted** by the workflow engine — command files and prompts receive the whole message only, via `$ARGUMENTS`/`$USER_MESSAGE`. (A legacy positional-substitution helper exists in the codebase but is not wired into the execution path.) Parse arguments inside the prompt or with a `bash:`/`script:` node instead.\n\n## Node Output Details (DAG Only)\n\n`$nodeId.output` resolves to the full text output of the upstream node. If the node used `output_format:` (structured output), the output is the JSON-stringified validated result. Bash/script output without `output_format` is stdout with the trailing newline trimmed; with it, stdout is certified as JSON under the same result contract (see `node-reference.md` → Result contracts). Loop/loop_group output is the final iteration's output with completion-signal tags stripped. An attention wait outputs its answer by form: `{text}` for `message`, `{decision, text}` for `approval` and `select`, `{decisions, text}` for `multi_select`; read fields as `$ask.output.decision` and `$ask.output.text`. A deprecated gate with authored `approval.decisions` also outputs JSON `{decision, text}`. A deprecated gate without authored decisions keeps the old behavior: its approval comment is output only when `capture_response: true`, otherwise `''`. Unknown or skipped producers resolve to an empty string (with a warning logged).\n\n`$nodeId.output.field` and nested paths such as `$nodeId.output.proposal.action` are **strict** (no-silent-drop) — they either resolve or **fail the consuming node**. Paths are object field names only: no array indexing, wildcards or expressions. The same paths work in templates, `when:` (which needs a scalar), whole-value `with:` bindings and `$LOOP_PREV..output.a.b`. Do not flatten a producer's schema to reach a nested field.\n\n- Producer has `output_format`: every segment must be a declared `properties` entry; a declared field or parent that is absent or null resolves to `''` (declared-optional). An undeclared segment, at any depth, fails `archon validate workflows` when the producer's schema is known at load, and fails the consumer otherwise (typo protection).\n- Schemaless producer (no `output_format` on the producing node): the output must be a JSON object containing every key on the path, with an object at each intermediate step — anything else (non-JSON output, missing key, a scalar or array mid-path) fails the consumer.\n- Producer skipped or pending: fails the consumer — guard the reference with `when:` or a permissive `trigger_rule`.\n\nValues: strings pass through; numbers/booleans stringify; objects/arrays are JSON-stringified.\n\nFor `workflow:` results, these field rules use the child's `returns:` node's\nschema, whose declared paths travel with the value and survive cold resume. The\ncaller cannot add or narrow the contract. An `include:` alias uses its selected\nproducer directly after flattening.\n\n### Artifact pointers\n\nReturn a small JSON value containing a pointer when a machine consumer needs a\nfile result. The reserved shape is:\n\n```json\n{\"type\":\"archon_artifact\",\"run_id\":\"\",\"path\":\"review/report.md\"}\n```\n\nUse the actual `WORKFLOW_ID` value for `run_id`, not the literal variable name.\nThe producer must first write the file under its `$ARTIFACTS_DIR`. Sibling keys\non the pointer are allowed. Before persisting the result, the engine validates\ntagged pointers against the producing run: its own run id, a nonempty relative\npath with no `..` segment or NUL, lexical containment, and an existing regular\nfile. Absolute/escaping paths, directories, missing files, and another run's id\nfail the producer.\n\nA `workflow:` parent and fan-out aggregate relay pointers unchanged without\nrevalidating them against the parent. Events and resume retain the run id and\nrelative path. The engine does not expand the pointer into an absolute path,\nread its contents into a prompt, or provide an in-workflow resolver. For prompt\nhandoffs inside the producing run, keep using `$ARTIFACTS_DIR/`.\n\nThe reader owns authorization, run reachability, and realpath containment at\nread time. Producer validation is not a read-side symlink guarantee; the artifact\nAPI's outstanding realpath check is tracked in #3160. Full semantics live in\nthe repository's `reference/variables.md` → Artifact pointers in a result.\n",".claude/skills/archon-cli/operate/managing-runs.md":"---\nname: archon-cli-manage-run\ndescription: Inspect, control, and resolve Archon workflow runs: list/get/status, approve, reject, respond, cancel vs abandon, resume. Read when a run is paused, failed, or the user asks about one.\n---\n\n# Managing runs\n\nEvery run-control verb, what it actually does, and the gate semantics that are\neasy to get wrong. Project listings scope by cwd; full run IDs remain globally\naddressable.\n\n## Output contract\n\n- `--json` → one clean JSON object on stdout; logs suppressed. Use when parsing.\n- No flag → human-readable text; diagnostics on stderr.\n\n## Overriding models for one run\n\nWhen the user asks to run on different models for a specific run, rebind the\ntier keywords or aliases at launch — the persistent config stays untouched:\n\n```bash\n# Rebind one or more tiers / @aliases for this run only; repeat per binding\narchon workflow run archon-ship --branch fix/x \"...\" \\\n --model large=pi/minimax/minimax-m3 \\\n --model small=openai/gpt-5-mini\n```\n\nSpec format: `=/` where `` is what\nthe named provider expects (for Pi backends that is itself a `/`\nref, e.g. `pi/minimax/minimax-m3`). An unknown tier/alias errors with the list\nof defined names.\n\nVerify before dispatching real work:\n\n```bash\n# dry-run prints each node's resolved provider/model without AI spend\narchon workflow run \"test\" --dry-run --model large=... # see 'runs on:' lines\n```\n\nFor reusable alternate setups, prefer a config layer instead of long flag lists\n(see `../setup/setup-and-config.md`, \"Alternate config layers\").\n\n## Verbs\n\n| Goal | Command |\n|---|---|\n| List recent runs (this project) | `archon workflow runs --json` |\n| Across all projects | `archon workflow runs --all --json` |\n| Filter by status / cap rows | `archon workflow runs --status running --limit 50 --json` |\n| One run's status/error | `archon workflow get --json` |\n| One run with per-node detail | `archon workflow get --verbose --json` |\n| One run with raw event rows | `archon workflow get --verbose --events --json` |\n| List a run's artifact files | `archon workflow artifacts --json` |\n| Read one artifact | `archon workflow artifacts ` |\n| List registered projects (and their `--project` keys) | `archon project list --json` |\n| Active runs (this project) | `archon workflow status --json` |\n| Active runs (all projects) | `archon workflow status --all --json` |\n| Block until the run ends or needs attention | `archon workflow wait --json` |\n| Every run that needs someone (this project / all) | `archon workflow attention --json [--all] [--label k=v]` |\n| The queue item one run stands for | `archon workflow attention --json` |\n| Every change in the queue, as it happens | `archon workflow attention --watch --json [--all] [--label k=v] [--after ]` |\n| Classify an item without answering it | `archon workflow attention label --occurrence --set k=v --json` |\n| Resolve a gate with any declared decision | `archon workflow respond [text]` |\n| Answer an attention wait in its form | `archon workflow answer --occurrence [--choose ]... [--text ]` |\n| Approve (default vocabulary) | `archon workflow approve [text]` |\n| Reject (default vocabulary) | `archon workflow reject \"\"` |\n| End a stalled turn on a running run, keep the run | `archon workflow end-turn ` |\n| Stop a running run (its live owner first) | `archon workflow cancel ` |\n| Mark paused/failed/orphaned run cancelled | `archon workflow abandon ` |\n| Resume failed/paused from completed nodes | `archon workflow resume ` |\n\n## Answering a decision well\n\nAn attention item is a question a run cannot settle. Most are written to be answered\nby whoever is on top of the runs, which is often you, not the user. Answer the ones\nthe user's standing direction already decides; bring the user only the ones that are\nunclear, risky, or outside what they have told you.\n\n1. Read the whole item: what is being decided, why it matters, the recommendation\n with its evidence and what would change it, the choices and what each does, and\n what happens if nobody answers. Open the evidence links before agreeing.\n2. Choose one of the declared choices. When none fits and the item offers `other`,\n choose it and say what to do instead.\n3. Give a reason in the text. Workflows record the answer's text with the decision,\n and some write it down as a ruling: the SDLC build queue and merge items owned by\n a build add it to the issue body as a dated \"Current scope\" section that later\n rounds work from. Enrolled own PRs keep the answer on the work item's merge\n decision entry and write no issue section. A bare choice teaches\n the next round nothing.\n4. Answer detached, so the continuation does not run in your shell:\n\n ```bash\n archon workflow respond \"\" --detach\n ```\n\n5. Pass `--occurrence ` when you answer from an item you read earlier: the\n `occurrence` on its stream line, or `attention.occurrence` from `workflow wait\n --json`. If the run has moved to a different pause, the answer is refused and the\n error names the current occurrence, instead of landing on a question you never\n read.\n\n## The approve/resume two-step\n\nWith `--json`, `approve`/`reject`/`respond` **record the decision and stop** —\nthis command does not execute the run (streaming output would corrupt the JSON).\nThe answered gate is a due continuation: a running `archon serve`, or\n`archon workflow wake [--watch]`, continues it without anyone resuming by hand.\nContainer runs (including a container write-back gate) are the exception: the\nhosts cannot continue them, so run `archon workflow resume ` yourself.\nTo record AND continue in this process:\n\n```bash\narchon workflow approve \"ship it\" # no --json: records + auto-resumes; background task!\n```\n\nA `wait: attention` pause (`attention.kind: \"attention\"`) is answered in the `form` it\nreports, with one of the `options` ids it lists:\n\n```bash\narchon workflow answer --occurrence --text \"done\" --json # message\narchon workflow answer --occurrence --choose use-dev --json # approval/select\narchon workflow answer --occurrence --choose a --choose b --json # multi_select\n```\n\n`approve`/`reject`/`respond