diff --git a/.claude/skills/docs/SKILL.md b/.claude/skills/docs/SKILL.md new file mode 100644 index 000000000..b141c0538 --- /dev/null +++ b/.claude/skills/docs/SKILL.md @@ -0,0 +1,65 @@ +--- +name: update-docs +description: Update documentation in docs/ based on recent code changes. Reads git history since a watermark commit, maps changed files to doc pages, and makes surgical edits to keep docs in sync with code. +--- + +# Update Docs + +Detect code changes since the last run and update affected documentation pages. + +- [references/mapping.md](references/mapping.md) — code-to-doc page mapping +- Follow `docs/CONTRIBUTING.md` and `docs/AGENTS.md` for writing style + +## Workflow + +### 1. Read watermark + +Read `.claude/skills/docs/watermark` for the last processed commit SHA. If the file is missing (first run), use the commit from 30 days ago as the starting point: `git log --before="30 days ago" --format=%H -1 main`. + +### 2. Gather changes + +Run `git log --oneline --no-merges --name-only ..HEAD` to get changed files and commit messages since the watermark. + +### 3. Map changes to doc pages + +Cross-reference changed files against the code-to-doc mapping in `references/mapping.md`. Also use judgment for unmapped files (e.g., new crates or modules that clearly affect user-facing behavior). + +Filter to user-facing behavioral changes only: +- New features, flags, commands, config options, node types +- Changed behavior, renamed APIs, new integrations +- Bug fixes that affect documented behavior + +Skip: +- Internal refactors with no behavior change +- Test-only changes +- CI/CD pipeline changes +- Dependency bumps +- Code style or linting changes + +If nothing affects docs, tell the user and stop. + +### 4. Read code and docs + +For each affected doc page: read the current MDX file and the relevant source files. Identify sections that are outdated, missing, or incorrect. + +### 5. Update doc pages + +Surgical edits only — change only affected sections. Preserve existing voice, structure, heading hierarchy, and Mintlify component usage. + +- Add code examples for new features (CLI commands, config snippets, DOT syntax) +- Insert rows into reference tables in logical position +- Add new sections for entirely new capabilities +- Update existing descriptions when behavior changes +- Never edit `docs/api-reference/arc-api.yaml` — that is the API workflow's source of truth + +### 6. Validate DOT examples + +If any updated page contains ` ```dot ` code blocks with `digraph` definitions, run `./test/docs/run_tests.sh validate`. Fix any failures before proceeding. + +### 7. Write watermark + +Write the output of `git rev-parse HEAD` to `.claude/skills/docs/watermark`. + +### 8. Summarize + +List updated doc pages and what changed in each. diff --git a/.claude/skills/docs/references/mapping.md b/.claude/skills/docs/references/mapping.md new file mode 100644 index 000000000..c4aae3fd8 --- /dev/null +++ b/.claude/skills/docs/references/mapping.md @@ -0,0 +1,38 @@ +# Code-to-Doc Mapping + +Which source files affect which doc pages. Use this as guidance — also apply judgment for unmapped files that clearly affect user-facing behavior. + +| Source | Docs | +|--------|------| +| `crates/arc-cli/src/main.rs`, `crates/arc-workflows/src/cli/mod.rs`, `crates/arc-workflows/src/cli/run.rs` | `docs/reference/cli.mdx` | +| `crates/arc-cli/src/cli_config.rs` | `docs/reference/cli-configuration.mdx` | +| `crates/arc-llm/src/cli.rs` | `docs/reference/cli.mdx` | +| `crates/arc-api/src/serve.rs` | `docs/reference/cli.mdx` | +| `crates/arc-workflows/src/parser/*.rs` | `docs/reference/dot-language.mdx` | +| `crates/arc-workflows/src/condition.rs` | `docs/reference/dot-language.mdx` | +| `crates/arc-workflows/src/cli/validate.rs` | `docs/reference/dot-language.mdx` | +| `crates/arc-workflows/src/stylesheet.rs` | `docs/workflows/stylesheets.mdx` | +| `crates/arc-workflows/src/transform.rs` | `docs/workflows/variables.mdx` | +| `crates/arc-workflows/src/handler/*.rs` | `docs/workflows/stages-and-nodes.mdx`, `docs/reference/dot-language.mdx` | +| `crates/arc-workflows/src/handler/human.rs` | `docs/workflows/human-in-the-loop.mdx` | +| `crates/arc-workflows/src/cli/run_config.rs` | `docs/execution/run-configuration.mdx` | +| `crates/arc-workflows/src/engine.rs` | `docs/core-concepts/how-arc-works.mdx` | +| `crates/arc-workflows/src/context/*.rs` | `docs/execution/context.mdx` | +| `crates/arc-workflows/src/checkpoint.rs` | `docs/execution/checkpoints.mdx` | +| `crates/arc-workflows/src/retro.rs`, `crates/arc-workflows/src/retro_agent.rs` | `docs/execution/retros.mdx` | +| `crates/arc-workflows/src/interviewer/*.rs` | `docs/execution/interviews.mdx` | +| `crates/arc-workflows/src/hook/*.rs` | `docs/agents/hooks.mdx` | +| `crates/arc-workflows/src/daytona_sandbox.rs` | `docs/integrations/daytona.mdx`, `docs/execution/environments.mdx` | +| `crates/arc-agent/src/tools.rs`, `crates/arc-agent/src/tool_registry.rs`, `crates/arc-agent/src/tool_execution.rs` | `docs/agents/tools.mdx` | +| `crates/arc-agent/src/v4a_patch.rs` | `docs/agents/tools.mdx` | +| `crates/arc-agent/src/cli.rs` | `docs/agents/permissions.mdx` | +| `crates/arc-agent/src/subagent.rs` | `docs/agents/subagents.mdx` | +| `crates/arc-agent/src/mcp_integration.rs` | `docs/agents/mcp.mdx` | +| `crates/arc-llm/src/catalog.rs`, `crates/arc-llm/src/providers/*.rs` | `docs/core-concepts/models.mdx` | +| `crates/arc-exe/src/*.rs` | `docs/integrations/exe-dev.mdx`, `docs/execution/environments.mdx` | +| `crates/arc-devcontainer/src/*.rs` | `docs/execution/devcontainers.mdx` | +| `crates/arc-slack/src/*.rs` | `docs/integrations/slack.mdx` | +| `crates/arc-sprites/src/*.rs` | `docs/integrations/sprites.mdx` | +| `crates/arc-mcp/src/*.rs` | `docs/agents/mcp.mdx` | +| `crates/arc-api/src/*.rs` | `docs/api-reference/overview.mdx`, `docs/api-reference/demo-mode.mdx` | +| `crates/arc-api/src/server_config.rs` | `docs/administration/server-configuration.mdx` |