awb-init

Initialize an analytics workbench

Run this skill's commands through the awb MCP tools when the host offers them, as the project's AGENTS.md Commands maps them; the command lines below are the fallback.

Build a project around one shared data foundation and zero or more investigations. Initialization establishes conventions and durable records, then hands the business question to awb-scope, which creates the investigation; data preparation, analysis, and packages follow on request.

1. Resolve the target

1. Use the project root the user names, otherwise the current directory when it is clearly the intended data project. A directory holding skill sources, design records, or an unrelated codebase is not one; obtain a separate target path before writing project files.
2. Inspect the target before changing it: its repository instructions, orientation, and ignore rules, and the README's active investigation.
3. Check whether the target or any directory above it holds a host-specific instruction file the current host reads in preference to AGENTS.md; Claude Code reads CLAUDE.md and skips AGENTS.md when a CLAUDE.md or CLAUDE.local.md is present. Such a file means the workbench rules in AGENTS.md may not be loaded. Leave that file to the user; report it with the import line that loads AGENTS.md (for Claude Code, a path relative to the file holding it: @AGENTS.md beside it, @../AGENTS.md from .claude/CLAUDE.md).
4. Merge conservatively. Existing files and project conventions are authoritative: create missing artifacts, add clearly compatible missing sections, and preserve existing content. When an existing artifact conflicts with the workbench model, explain the conflict and ask for the project-specific decision.
5. Use the existing Git repository when the target is inside one. Otherwise initialize a local repository, with no commit or remote. When Git is absent or git init fails, record Code history: none (<reason>) on README's Code history line in step 3 and report it once. When a later run finds or creates a repository, set the line back to Code history: Git.

A rerun is reconciliation: settled records, answered questions, working paths, and customized templates stay as they are.

For a repair or an update to newer skills, follow references/repair.md, then report under step 5; otherwise continue below.

2. Get the business question

A new project starts from a business question. Ask for it in one line before creating any project file, unless the user gave it; set up the project without an investigation only when the user explicitly says there is no question yet. Do not interview here: step 4 hands the question to awb-scope. In an existing workbench, a new question or a change of scope belongs to awb-scope, not this skill.

3. Create the project foundation

Adapt asset files to the target; their instructional comments and example rows are guidance, not project facts. The user-level skills serve every project, so the project holds only these files.

1. Adapt the orientation, ignore rules, and agent instructions into missing root files; merge .gitignore rules one by one, each negation after every rule it overrides. A repair reconciles existing ones through references/repair.md. When the user has named where landed data or released packages are kept, write it on README's Landed data is kept at or Released packages are kept at line: an absolute path, a path starting with ~, or one relative to the project root starting with ./ or ../, or none chosen when they decline; the helpers copy only to such a path, so any other answer, such as a URL, leaves copying to the user.
2. When merging into an existing AGENTS.md, link both guides relatively and check the links resolve.
3. Install the project helpers, workbench guides, and the foundation/references/ folder, and declare the helpers' packages, with the interpreter that will run the project's analysis; the installer records it as README's Project interpreter, which runs every workbench command. When the project has no virtual environment and the user named no interpreter, first create .venv in the project with Python's venv module, run by Python 3.12 when installed, else by the system's default Python 3 when it is 3.10 or later, and install duckdb and pandas into it; if that fails, ask once which interpreter to use. Use the awb MCP server's setup tool when the host offers it, passing that interpreter's absolute path as interpreter; without it, setup runs under README's interpreter, else the project's .venv or venv, else the server's own, which it refuses to record while that lacks the packages. Run the installer as a black box; --check reports without writing. A repair runs it from references/repair.md instead.

   python3 <skill-directory>/scripts/install_helpers.py <project-root>

Report in one line the interpreter its interpreter entry records. When it prints an install command and its interpreter is in_project, run that command yourself and report it in one line; ask before installing into an interpreter outside the project. Carry into the report every files entry not installed or current, a vscode_mcp that is different, unreadable, or tracked, any requirements entry marked missing or unread (a line the helpers could not read, which may declare a missing package), and any install not run; the user adds or runs those.

1. Create shared foundation records as their conditions fire: the source register when a source becomes a real candidate, the catalog when a dataset, view, or deliberate cache exists, the quality record when a shared limitation, check, or correction is known, the dataset checks when a dataset's publication checks are declared, and the glossary when shared vocabulary is resolved. foundation/review-rules.md has no template: python3 src/awb.py review-rules add creates it with the first rule. Keep an existing project's format when it serves the same responsibility; create each ledger only with content.
2. Create data/raw/, data/parquet/, data/cache/, foundation/views/, .env.example (credential variable names, under the data guide's rule), and further code or configuration only when their first content exists; the installer creates foundation/references/.

Package templates and deliveries/ stay absent. If the user explicitly asks for a package, finish initialization, then invoke the sibling `awb-package` skill.

4. Hand off the question

With the foundation in place, invoke the sibling `awb-scope` skill with the user's question. It interviews the user, creates the investigation's brief, state, history, run script, settings, and question ledger, and points the README's Active investigation line at it. When the hand-off shares a turn with setup, run awb-scope's first interview round before it creates the investigation, asking it in this report, one choice per numbered decision. Without a question, leave that line at none.

5. Report

Report in plain words, in at most these five items, omitting any that do not apply:

• the project root;
• the question handed to awb-scope, with its first interview round or the investigation it created, or that there is none yet;
• any host instruction file from step 1, with its import line;
• each item the user must act on, with its impact: what it changes for them and what the workbench does meanwhile, such as installer items step 3.3 carries, unresolved decisions and file conflicts, no code history, or an awb MCP server the host has not registered or cannot start; and
• the next request: answering the interview round, or awb-status to see where things stand.

A repair report adds what references/repair.md says to report, after these items.

In VS Code, ask the user to start an unlisted awb server from .vscode/mcp.json; elsewhere, offer in one line the host's registration command that python3 <skill-directory>/scripts/install_helpers.py --mcp-config <host> (claude, codex, or copilot for Copilot CLI) prints, run with Python 3.12 when installed, else a stable Python 3.10+ interpreter, outside any project virtual environment, with any interpreter warning, and its printed entry and destination as the fallback; until then, helpers run as terminal commands the host may ask the user to approve. Leave running the command and merging user configuration to the user. If registered but unavailable, report the host's diagnostic instead.

Unless README's Code history line says none, commit when the user asks or as its Commits line allows, and after a repair suggest committing it as one commit so it can be reviewed and reverted as a unit, unless you already suggested a commit this session. Initialization is complete when the project conventions are usable, foundation records exist for the knowledge already established, the user's business question has gone to awb-scope, and the work has stopped short of packages and analysis the user has not requested.