Docs

Publish workflows from GitHub. Install with the smithers-directory CLI. Run with smithers-orchestrator.

Manifest: smithers-directory.json

{
  "name": "code-review-workflows",
  "description": "Smithers workflows for code review.",
  "workflows": [
    {
      "name": "code-review",
      "entry": "workflows/code-review.tsx",
      "description": "Reviews a repo and waits for approval.",
      "tags": ["code-review"],
      "env": ["ANTHROPIC_API_KEY"],
      "capabilities": ["agent", "shell", "approval"],
      "files": ["components/code-review", "prompts/code-review.mdx"],
      "docs": [
        {
          "title": "Operator guide",
          "path": "docs/code-review.md",
          "summary": "Inputs, approvals, and safe operating notes.",
          "showOnInstall": true,
          "exampleCommand": "bunx smithers-orchestrator workflow run code-review --input '{...}'"
        }
      ]
    }
  ]
}

docs is the canonical way to ship workflow-specific markdown that agents and operators can find after install.

Operator docs

Declare docs when a workflow has required inputs, run modes, review behavior, or operational caveats that should survive terminal scrollback. Each referenced markdown file is copied into the consuming repository under .smithers/docs/.

Fields

title: required display name.
path: required repo-relative .md or .mdx file.
summary: optional short post-install description.
showOnInstall: optional; hidden only when set to false.
exampleCommand: optional quick run command.

Behavior

docs/code-review.md installs as .smithers/docs/code-review.md.
guides/runbook.md installs as .smithers/docs/guides/runbook.md.
Install output prints up to three visible guides plus one quick-run command.
list, list --json, check, and check --json surface doc paths.

Path safety is strict: absolute paths, traversal segments, generated directories, node_modules, .git, and Smithers runtime directories are rejected. A workflow can declare up to eight docs. Duplicate paths are accepted only when metadata is identical.

// Legacy single-doc alias, accepted for compatibility:
{
  "name": "code-review",
  "entry": "workflows/code-review.tsx",
  "operatorGuide": "docs/code-review.md"
}

Workflow support files

Use files to declare reusable helpers, prompts, and components needed by a workflow. Explicit files are installed only with the selected workflow.

{
  "name": "quality-check",
  "entry": ".smithers/workflows/quality-check.tsx",
  "files": [".smithers/lib/quality"]
}

CLI commands

npx smithers-directory add owner/repo

npx smithers-directory add owner/repo@workflow-name

npx smithers-directory find code-review

npx smithers-directory list

npx smithers-directory update

npx smithers-directory check

Agents and CI

Without a TTY, the CLI does not prompt. It exits with instructions to run smithers-directory add --help if required flags are missing.

npx smithers-directory add --help

npx smithers-directory add owner/repo --list

npx smithers-directory add owner/repo --workflows code-review,lint --yes

Disclaimer

smithers.directory is an independent community directory. Review workflow source, required env vars, and capabilities before installing or running workflows in production environments.