Skip to content

Add the getting-started, best-practices and vertical-building guides - #191

Open
lbx154 wants to merge 2 commits into
devfrom
docs/tutorials-and-best-practices-20261001
Open

lbx154 wants to merge 2 commits into
devfrom
docs/tutorials-and-best-practices-20261001

Conversation

@lbx154

@lbx154 lbx154 commented Sep 30, 2026

Copy link
Copy Markdown
Owner

Why

New users had no path from installation to a finished task, no guidance on writing objectives or steering a running project, and no worked example of building a vertical. The week plan asks for an entry-level tutorial (command line, web, desktop), best practices with real examples, and a vertical-building guide, all under docs/ with an entry in the README.

What changes

  • docs/getting-started.md: install, first-time setup and argus doctor, then a first task by each of three paths (command line, web UI, desktop app), what "finished" looks like, and where state lives. Every command was checked against the CLI in this checkout; the example runs are real projects with times and costs from their logs.
  • docs/best-practices.md: writing an objective (what the Manager, Planner and Reviewer each read from it), changing direction while a project runs (nudge, message, answer, ask, and how they differ), choosing the backend and model per role, controlling spend (daily cap, provider caps, the unpriced-cost policy), and which tasks suit Argus. Each point carries an example from one of three real projects run on 2026-09-30; numbers are measurements, not rules. The spend section states that since Price warm Copilot ACP turns from the session event log; explain the cost-policy refusal #179 and Settle Copilot turns Argus interrupted before the CLI recorded them #183 the default block policy no longer stalls a fresh subscription install.
  • docs/building-a-vertical.md: a small real vertical (lab_notebook) from the contract's names, two built-ins to learn from, stages and checklists, skills, packaging with a local catalog, installing it and confirming Argus sees it, and publishing to the store. The finished example is under examples/verticals/ with build_local_catalog.py, which builds the zip and catalog the guide shows.
  • README.md: a Tutorials section linking the three guides.

No code paths change; examples/ is not scanned by the vertical registry or the tests.

Validation

  • The guide's contract check runs on the example and prints ('measure', 'report') none staged; the local-catalog build and argus verticals install lab_notebook into a throwaway home were run while writing.
  • tests/skills/test_vertical_plugins.py and tests/skills/test_skill_frontmatter_integrity.py: same result as on clean dev (one pre-existing local failure, test_store_verticals_are_discovered_with_origin_store, caused by a pip-installed argus_verticals in this machine's venv).
  • ruff check examples clean.

Documentation and config-related wording were checked against argus/core/knobs.py and argus/daemon/config.py; one unverified point is marked with an HTML comment in the vertical guide (the external argus-verticals repository's contribution procedure).

🤖 Generated with Claude Code

lbx154 and others added 2 commits September 30, 2026 03:32
Three guides under docs/, linked from a new Tutorials entry in the
README:

- getting-started.md: from an empty machine to a finished first task by
  the command line, the web UI and the desktop app. Every command was run
  against this checkout (argus 0.1.8); the example runs are real projects
  from 2026-09-30 with their times and costs taken from their logs.
- best-practices.md: how to write an objective, how to change direction
  while a project runs, how the backend and model are resolved per role,
  how spend is bounded, and which tasks suit Argus. Each point carries an
  example from one of three real projects (the GPU roofline campaign, the
  damped-oscillator task, the fresh-install trial); numbers are
  measurements, not rules. The spend section notes that the default
  unpriced-cost policy no longer stalls a fresh subscription install since
  #179 and #183.
- building-a-vertical.md: a small real vertical, lab_notebook, from the
  contract's names and two built-ins to learn from, through stages,
  checklists and skills, to packaging, a local catalog, installing it and
  publishing to the store. The finished example lives under
  examples/verticals/ with a helper that builds the zip and catalog; the
  guide's contract check and install steps were run.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The layout map must name every top-level directory; the guides' worked
example directory was missing from it.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant