AGENTS.md git:20260914.d768486A

Immutable. This exact content never changes and is served at /api/v1/blob/72c478fdee248569.

# AGENTS.md

Shared contributor guidance for every coding harness working in `wise-claude`.
This file contains project instructions, not a loadable agent registry.
Keep harness-specific instructions in that harness's configuration file.

## Repository and runtime

- `plugins/wise/` is the canonical, hand-edited Wise plugin. The marketplace
  index at `.claude-plugin/marketplace.json` points to it. There is no build
  or generation step.
- The workflow engine is Python 3.11+ and executes YAML v2 workflows. Its
  provider adapters support Claude, Codex, Cursor, Gemini and Grok. The main
  conversation's client and the provider running a child are separate choices.
- Read [CONTRIBUTING.md](CONTRIBUTING.md) and the relevant
  [workflow documentation](docs/wise/) before changing the plugin. Consult
  the instructions within the affected subtree as well.

## Code map

- `plugins/wise/skills/`: skill entrypoints and skill-local resources.
- `plugins/wise/references/`: shared procedures. Change shared behavior here
  rather than duplicating instructions across skills.
- `plugins/wise/agents/`: SDLC role cards, catalogued in
  [the plugin agent index](plugins/wise/AGENTS.md).
- `plugins/wise/workflows/`: bundled workflow definitions, prompts and READMEs.
- `plugins/wise/engine/wise_engine/`: schema (`defs.py`), scheduling,
  execution, persisted state, preflight and provider adapters.
- `plugins/wise/engine/tests/` and `plugins/wise/tests/`: automated tests.
- `plugins/wise/scripts/` and `plugins/wise/hooks/`: helpers and plugin hooks.
- `scripts/validate_repo.py`: repository structure and documentation checks.
- `docs/wise/`: user and contributor reference documentation.

## Workflow and interaction contracts

- The engine owns workflow scheduling, model/effort resolution and persisted
  state. The main harness calls its MCP tools or CLI, not workflow steps itself.
- Follow [workflow host control](plugins/wise/references/workflow-host-control.md)
  for installation discovery, initialization, question routing and gates.
  Identify the active main client, its GUI/TUI surface and available question
  tools rather than inferring capabilities from the provider name.
- The main harness owns user interaction: prefer its permitted native control,
  then a usable rendered MCP form, then the documented main-harness text
  fallback. Never launch a separate terminal or system dialog as a fallback.
  Defaults and asynchronous display acknowledgements are not user answers.
- Children relay questions through Wise or their parent. Pass applicable
  project instructions and task constraints to delegated children; do not
  assume they inherit the main conversation. Preserve autonomous no-prompt
  rules and explicit consent gates defined by the invoked skill.

## Editing and validation

- Keep `plugins/wise/.claude-plugin/plugin.json` as the plugin version source.
  Follow CONTRIBUTING's versioning rules when changing shipped plugin files.
- Keep workflow READMEs synchronized with their YAML and prompts. When editing
  `plugins/wise/agents/<name>.md`, update the plugin agent index in the same
  change. Role cards, not a duplicated roster, are the source of truth.
- Pin external marketplace sources to commit SHAs. Retain the plugin license.
- Run `just install` when the pinned development environment is missing.
  Run `just check` before committing: repository validation, pytest, mypy,
  Ruff, formatting checks, Python compilation, JSON and shell syntax checks.