diff --git a/CHANGELOG.md b/CHANGELOG.md index 3c291599..51577146 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,13 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [Unreleased] + +### Added +- `actual advisor` command: ask the Advisor org-scoped architecture questions from the terminal and print the answer with any related ADRs (requires signing in with `actual login`) +- Repository scoping for `actual advisor`: `--repo ` to target a connected repository, automatic detection from the working tree's `origin` remote, a scope remembered per repository, the `none` and `auto` keywords to pin org-level or reset, and `--show-scope` to print the active scope +- Documentation for the advisor command and repository scoping in the README and Getting Started guide + ## [0.1.4] - 2026-03-31 ### Fixed diff --git a/README.md b/README.md index 181586d6..e5cbf8ab 100644 --- a/README.md +++ b/README.md @@ -116,10 +116,44 @@ you've written yourself. | Agents | `--output-format agents-md` | `AGENTS.md` | | Cursor Rules | `--output-format cursor-rules` | `.cursor/rules/actual-policies.mdc` | +## Ask the Advisor + +Beyond generating context files, `actual` can answer architecture questions +directly. `actual advisor` sends your question to the Advisor and prints a +tailored answer, plus any related ADRs, in the terminal. + +The Advisor works against your Actual AI organization, so sign in first: + +```bash +actual login +actual advisor "Should new services talk over gRPC or REST?" +``` + +By default the answer is scoped to the repository you're standing in: +`actual` reads the working tree's `origin` remote and, if a connected +repository matches, scopes the question to it. If nothing matches, the +question runs at the organization level. + +Set the scope explicitly with `--repo`: + +```bash +actual advisor --repo actual-cli "..." # scope to a repo by name +actual advisor --repo owner/actual-cli "..." # disambiguate a shared name +actual advisor --repo none "..." # ask at the organization level +actual advisor --show-scope # print the active scope and exit +``` + +The scope you choose is remembered per repository for later calls from the +same working tree; `--repo auto` forgets the pin and returns to +auto-detection. See +[Getting Started](docs/GETTING_STARTED.md#ask-the-advisor) for the full flag +reference. + ## Commands ``` actual adr-bot # analyze repo & write AI context files +actual advisor # ask the Advisor an architecture question actual status # check output file state (managed markers, staleness) actual auth # verify authentication actual config show # view current configuration diff --git a/docs/GETTING_STARTED.md b/docs/GETTING_STARTED.md index f0643065..577de7c8 100644 --- a/docs/GETTING_STARTED.md +++ b/docs/GETTING_STARTED.md @@ -111,10 +111,59 @@ By default, `actual adr-bot` writes to `CLAUDE.md`. Content is wrapped in manage | `--show-errors` | Stream runner subprocess stderr in real time | | `--api-url ` | Override ADR bank API endpoint | +## Ask the Advisor + +`actual advisor` asks the Advisor an architecture question about your organization's codebase and prints the answer, along with any related ADRs, to your terminal. Unlike `adr-bot`, this command talks to your Actual AI account rather than a local AI runner, so sign in first with `actual login`. + +```bash +actual login +actual advisor "When should we introduce a message queue?" +``` + +The command starts an Advisor job and polls until the answer is ready (up to a few minutes), writing progress to stderr and the final answer to stdout. + +### Scoping the question to a repository + +By default the question is scoped to the repository you're standing in. `actual` reads the working tree's `origin` remote and, if one of your organization's connected repositories matches, scopes the answer to that repo. If nothing matches (or you aren't inside a git repo), the question runs at the organization level. + +Override the scope with `--repo`, which accepts a repository **name**, an `owner/name` form (to disambiguate a name shared across owners), or a repo **UUID**: + +```bash +actual advisor --repo actual-cli "..." # by name +actual advisor --repo owner/actual-cli "..." # by owner/name +actual advisor --repo 3f2a1c9e-... "..." # by UUID +``` + +Two values are reserved keywords rather than repository names: + +| Value | Effect | +|-------|--------| +| `--repo none` | Pin the scope to the organization level (opt out of repo scoping) | +| `--repo auto` | Forget any pin and return to git-remote auto-detection | + +The scope you choose is **remembered per repository** (keyed by the working tree's `origin` remote) and reused on later `actual advisor` calls from the same tree, so you don't have to repeat `--repo` each time. Inspect the active scope without asking a question: + +```bash +actual advisor --show-scope +``` + +To scope to a repository literally named `none` or `auto`, pass its `owner/name` form or UUID instead of the bare keyword. + +### Advisor flags + +| Flag | What it does | +|------|-------------| +| `` | The architecture question to ask. Optional when the command is used only to change or show scope (`--show-scope`, or a bare `--repo` value with no question) | +| `--repo ` | Scope to a connected repository by name, `owner/name`, or UUID; `none` pins org level, `auto` resets to auto-detection. Omit to auto-detect from the `origin` remote | +| `--show-scope` | Print the remembered scope for the current repository and exit (reads local config only, no query) | +| `--org ` | Organization to scope to (defaults to your signed-in org). Passing `--org` without `--repo` runs a one-shot organization-level query without changing the remembered scope | +| `--api-url ` | Advisor API base URL (defaults to production; also settable via the `ACTUAL_API_URL` environment variable) | + ## Commands ```bash actual adr-bot # analyze repo & write AI context files +actual advisor # ask the Advisor an org-scoped architecture question actual status # check output file state (managed markers, staleness) actual auth # verify the configured AI runner is authenticated actual config show # view current configuration