From 3aa0e0d47bc53a45a46468916f8fe66dc979ae90 Mon Sep 17 00:00:00 2001 From: matthalltech Date: Wed, 1 Apr 2026 12:44:01 +0000 Subject: [PATCH] docs: update GETTING-STARTED.md --- GETTING-STARTED.md | 86 ++++++++++++++++++++-------------------------- 1 file changed, 38 insertions(+), 48 deletions(-) diff --git a/GETTING-STARTED.md b/GETTING-STARTED.md index 978154e..802b843 100644 --- a/GETTING-STARTED.md +++ b/GETTING-STARTED.md @@ -1,16 +1,16 @@ --- -title: AgentLab — Getting Started +title: Developing with Claude — Getting Started document_type: how-to status: active created: 2026-04-01 updated: 2026-04-01 tags: - - agentlab - - onboarding + - claude + - ai-development - getting-started --- -# AgentLab — Getting Started +# Developing with Claude — Getting Started > *Run AI coding agents safely on your own machine. Works on a laptop. Grows as far as you want to take it.* @@ -135,12 +135,12 @@ Machine discovery report: Follow the plan Claude produces. The typical starting baseline: 1. Create a workspace root folder (e.g. `~/AgentLab/` on Mac/Linux, `C:\AgentLab\` on Windows) -2. Create subfolders: `vault-repo/`, `work-rw/`, `drop-ro/` -3. Clone this repo into `vault-repo/` +2. Create subfolders: `your-repo/`, `work-rw/`, `drop-ro/` +3. Initialise a Git repo inside `your-repo/` and create a `README.md` 4. Install Docker if not already present -5. Authenticate Claude Code -6. Run `bootstrap.sh` to verify tool state -7. Ask Claude to read `LLM-ENTRYPOINT.md` and confirm it can navigate the repo +5. Set up a devcontainer or Docker Compose file based on the plan Claude produced +6. Authenticate Claude Code inside the container +7. Ask Claude to describe the repo structure and confirm it can navigate it Do not add more until this works cleanly. @@ -155,15 +155,15 @@ The fix is simple: force Claude to fetch current documentation before writing an **Run this prompt once Claude is up and running in your repo:** ``` -Read LLM-ENTRYPOINT.md and follow the mandatory read order. +Review the repo structure — read the README and any other docs present. Then do the following: 1. Fetch the current Claude Code documentation from the official Anthropic docs site 2. Store a summary of the key capabilities, current model IDs, and any recent changes in docs/vendor-docs/anthropic/ -3. Review the existing repo rules in .claude/rules/ and identify any that reference outdated model names, deprecated flags, or stale API patterns -4. Propose any updates needed to bring the rules and configuration in line with current Claude Code behaviour +3. Identify any repo rules or config that reference outdated model names, deprecated flags, or stale API patterns +4. Propose updates needed to bring the configuration in line with current Claude Code behaviour -After completing this, confirm what version of Claude Code is installed in this environment and whether the installed version matches what the docs describe. +After completing this, confirm what version of Claude Code is installed and whether it matches what the docs describe. ``` This seeds the repo with verified, current documentation that Claude can reference instead of guessing. @@ -182,8 +182,6 @@ Claude will push back on this — it will say it already knows. It does not. Its --- ---- - ## Optional — Voice Input Typing long prompts into a terminal is a friction point. Local voice-to-text removes it. Audio is transcribed on your machine and inserted as text into whatever is focused — your terminal, your editor, Claude Code — without going to a cloud transcription API. @@ -208,10 +206,10 @@ The container is disposable. The bind-mounted folders on your host are not — t | Folder | What's in it | |---|---| -| `~/AgentLab/vault-repo/` | The entire repo — all docs, scripts, state, rules | +| `~/AgentLab/your-repo/` | The entire repo — all docs, scripts, state, rules | | `~/AgentLab/work-rw/` | Working files and scratch space written by agents | | `~/.ssh/` | SSH keys — lose these and you are locked out of every server | -| `~/.ansible/vault-pass` | Ansible vault password — lose this and all encrypted secrets are unrecoverable | +| Infrastructure secrets | Vault passwords, automation credentials — losing these makes encrypted secrets unrecoverable | | Voice app model files | Usually in `~/Library/Application Support//` on Mac — 100MB–1.5GB, slow to re-download | The git repo itself is partially protected by any remote (GitHub, Forgejo) — every push is a backup of committed work. Uncommitted work and non-git content (`work-rw/`, logs) need explicit backup coverage. @@ -278,7 +276,7 @@ It used training data instead of current docs. Enforce the fetch-before-write ru Something was written to the container overlay layer instead of a bind mount or named volume. Everything important needs to live on a mounted path or in the repo. The container itself is disposable. **"Claude keeps asking about things I already told it last session."** -Claude has no memory of previous sessions unless it is given one. The repo is the memory — write state into documents and have Claude read them at the start of each session. The `LLM-ENTRYPOINT.md` read order exists precisely for this. +Claude has no memory of previous sessions unless it is given one. The repo is the memory — write state into documents and have Claude read them at the start of each session. Create a startup document (e.g. `ENTRYPOINT.md`) that Claude reads first every session to rehydrate context. **"Two sessions seem to be conflicting."** Multiple Claude Code sessions can run simultaneously. Before editing any shared file (settings, hooks), check whether another session has recently modified it. The git history is your audit trail. @@ -292,49 +290,41 @@ It recommended from training data without verifying current status. Ask it to ch **Review what is open and decide what to do next:** ``` -Read LLM-ENTRYPOINT.md and follow the mandatory read order. -Then tell me: what is the current system state, what is unresolved, and what is the highest-leverage thing I can work on today? +Read the repo README and any state documents present. +Tell me: what is the current system state, what is unresolved, +and what is the highest-leverage thing I can work on today? ``` **Plan a new component:** ``` -Read LLM-ENTRYPOINT.md and follow the mandatory read order. -I want to add [component]. -Before writing anything, fetch the current documentation for every third-party component involved. +I want to add [component] to this repo. +Before writing anything, fetch the current documentation for every +third-party component involved. Do not rely on training data. Then propose a phased plan, flag any open decisions, and list what I need to provide. ``` **Understand the agent collaboration model:** ``` -Read docs/agent-handbook.md. -Explain how the agents in this repo are expected to collaborate — what each one does, how they hand off work, and what prevents them from conflicting. +Review any agent configuration and rules in this repo. +Explain how the agents are expected to collaborate — what each one does, +how they hand off work, and what prevents them from conflicting. ``` --- -## Key Files +## Files to Create in Your Own Repo -Start here when orienting yourself or Claude to the system. +These are the documents that make an AI-assisted repo work well. None of them are magic — they are just Markdown files with clear purposes. Build them gradually as you need them. -| File | What it is | -|---|---| -| `LLM-ENTRYPOINT.md` | Where every agent session begins — mandatory read order and environment facts | -| `AGENTS.md` | Cross-agent operating contract — branch model, permissions, standards | -| `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next | -| `docs/priorities.md` | Current priority order | -| `docs/agent-handbook.md` | Shared agent onboarding and operating protocol | -| `docs/open-loops.md` | Persistent backlog of unresolved items across all sessions | -| `bootstrap.sh` | Idempotent runtime verification — run after any container rebuild | -| `.claude/rules/` | Repo-level rules enforced for every Claude session | +| File | Purpose | Create it when… | +|---|---|---| +| `README.md` | Human-facing landing page — what this is, current state, key links | Day one | +| `ENTRYPOINT.md` | Agent session startup — what to read first, environment facts, execution boundaries | Once you have more than one doc | +| `AGENTS.md` | Operating contract for AI agents — what they can do, what requires approval | Before doing serious work with agents | +| `docs/system-plan.md` | Planning source of truth — what is built, what is open, what is next | When you have infrastructure to track | +| `docs/open-loops.md` | Persistent backlog across sessions — so nothing falls through the cracks | When unresolved items start accumulating | +| `bootstrap.sh` | Idempotent setup script — verifies the workspace is in the expected state after rebuilds | Once your setup has more than 3 steps | +| `.claude/rules/` | Repo-level rules loaded every Claude session — safety, style, workflow | When you have patterns you keep repeating | +| `docs/vendor-docs/` | Current third-party documentation fetched and stored locally | Before writing any code that uses an external library | -**Become familiar with these before doing serious work:** - -1. `LLM-ENTRYPOINT.md` — read order and execution boundaries -2. `AGENTS.md` — what agents can and cannot do -3. `docs/agent-handbook.md` — how sessions start, how state is handed off, what the authority order is -4. `docs/system-plan.md` — what is verified live vs what is aspirational -5. `.claude/rules/sdk-docs-before-code.md` — the rule that prevents stale-training-data mistakes - ---- - -*If you are an AI agent reading this: read `LLM-ENTRYPOINT.md` next and follow the mandatory read order before taking any action.* +**The most important habit:** Ask Claude to fetch current docs before writing any code that uses a third-party library, API, or tool. Training data is frozen. The docs are not.