arg0-vibecode

Workspace onboarding CLI for agentic development. One command turns a folder of unrelated repos into a curated VS Code + agent workspace: agents installed, .code-workspace written, knowledge graph indexed, and only the skills the workspace justifies enabled.

Status: v0.1 (F-001–F-006) and v0.2 (F-007–F-009) implemented, v0.2 shipped as 0.2.2. v0.4 (F-011, F-012), v0.5 (F-013) and v0.6 (F-014) implemented since. v0.3 (F-010) is scoped only. Two items remain wip by decision rather than by omission — F-013-T5 needs a real model run, and F-014-US2 has a criterion no test can close. Each says so in its own status cell.

Planned surface

arg0-vibecode init [--yes] [--dry-run]   # step-by-step onboarding
arg0-vibecode sync                       # reconcile drift, apply deltas only
arg0-vibecode doctor [--json]            # read-only health report
arg0-vibecode plan --json                # the plan, machine-readable, writes nothing
arg0-vibecode report                     # what happened, and every file touched

v0.2 (PRD v0.2 F-007, implemented):

arg0-vibecode configure [--global|--local] [--yes] [--show]   # generate .vibecode/config.toml
arg0-vibecode init  [--global|--local]   # --local (default) writes only inside the workspace
arg0-vibecode sync  [--global|--local]   # both commands obey .vibecode/config.toml

Documentation

| Doc | What | |---|---| | PRDs/prd.md | Problem, scope, flows, decision log, risks | | architect/spec_v0.1.md | Binding spec: CLI surface, Step contract, state, registry, acceptance criteria | | architect/architect.md | Modules, DAG, data contracts, blast radius | | architect/architect_common.md | Stack, patterns, naming, quality + security gates, review checklist | | architect/feature_v*_F-0*_architect.md | Low-level design, one per feature (F-001–F-014) | | ADRs/ | 20 accepted architecture decisions | | tests/testing_strategy.md | Three test layers, coverage gates, pipeline | | deployment/deployment_strategy.md | Publish, versioning, rollback, CI/CD | | research.md | Verified integration facts + open questions | | tasks/tasks.md | Master task index; one tasks file per feature from v0.4 onward | | ddd/ | Five domains — onboarding, scope, skill selection, prompt templates, skill routing. Read before the architecture | | runbook/ | Six hands-on procedures: development, testing, troubleshooting, deployment, routing a skill, prompt templates | | route/ | Prepared implementation plans for agents — python3 docs/arg0-vibecode-Specs/route/route.py --version v0.2 --id F-007 | | tests/test_v*_F-0*.md | Per-feature low-level test plans | | docs/entrypoint/ | How to dev / test / deploy / observe |

Documentation hub layout

docs/
├── arg0-vibecode-Specs/
│   ├── PRDs/        prd.md · prd_<V>_<F-ID>-<slug>.md      what problem, what scope
│   ├── ddd/         domain_DOM-nnn-<slug>.md               what the words mean   (read first)
│   ├── ADRs/        adrs_ADR-nnnn-<slug>.md                decisions, with alternatives
│   ├── architect/   architect{,_common}.md                 system + conventions
│   │                spec_v0.1.md · spec_v0.2.md            the binding contract
│   │                feature_<V>_<F-ID>_architect.md        low-level design
│   ├── tasks/       tasks.md · tasks_<V>_<F-ID>.md         ordered slices, with status
│   ├── tests/       testing_strategy.md · test_<V>_<F-ID>.md   what must be asserted
│   ├── runbook/     runbook_<TYPE>_RB-nnn-<slug>.md        how to actually do it
│   ├── deployment/  deployment_strategy.md                 publish, versioning, rollback
│   ├── research.md                                         verified facts + open questions
│   └── route/       route.py · rule_<V>_<F-ID>.json        entrypoint for agents
├── entrypoint/      how-to-{dev,test,deploy,observability}.md
└── project-management/arg0-vibecode/
    └── Speculate/   product-backlog.md · product-backlog-<F-ID>_<slug>.md

Read a feature's documents in route order:

python3 docs/arg0-vibecode-Specs/route/route.py --version v0.2 --id F-007

Features (v0.1)

| ID | Feature | |---|---| | F-001 | Agent bootstrap — claude-code, pi, opencode, codex, github-copilot | | F-002 | Workspace assembly — scan, classify, write <project>.code-workspace | | F-003 | Knowledge graph provisioning + workspace-scoped MCP wiring | | F-004 | Root skills from arg0-ai/arg0-skills@personal, symlinked | | F-005 | Knowledge-graph baseline across every member repo | | F-006 | Skill curation — enable only what the workspace justifies |

Features (v0.2 — implemented)

| ID | Feature | |---|---| | F-007 | Context scope — --local (default) confines every write to the workspace; --global is opt-in | | F-008 | configure — generates .vibecode/config.toml; policy becomes a file, not a prompt | | F-009 | Config-driven init/sync — CLI > config > defaults, resolved once, printed in plan --json |

Features (v0.4–v0.6 — implemented)

| ID | Feature | |---|---| | F-011 | Skill selection — skills.selection picks a category or an individual skill; picks narrow curation, they never replace it (ADR-0018) | | F-012 | The name-collision check applies to the linked set, not the scanned source — a skill's identity is its category and name (ADR-0017) | | F-013 | Prompt templates distilled from skills, unusable until a person authorizes them (ADR-0019) | | F-014 | ask-arg0 — a router over every skill in ./skills, wrapping the vendored ask-matt rather than replacing it (ADR-0020) |

F-011 and F-012 are shipped CLI behaviour, in src/core/. F-013 and F-014 are maintainer tooling — they live under scripts/ and skills/ and never enter dist, because distilling a template reads a model and routing skills is this repository's own housekeeping:

npx vitest run test/router/check.test.ts          # does ask-arg0 still cover every skill?
ANTHROPIC_API_KEY=… npm run evaluate-templates    # does each template reach its own skill?

Principle

Curation over accumulation. Default is nothing installed. Every artifact must be justified by something detected in the workspace, and the justification is recorded.

The blast radius is declared, not discovered (v0.2). Before a single write, one file (.vibecode/config.toml) and one word (scope) tell you every path a run may touch.

Provenance decides who may write a document (v0.6). 36 of this workspace's 57 skills are vendored from installed plugins and are replaced wholesale on the next update. A vendored artifact is read, delegated to, and depended on — it is never where a local decision is recorded.