Usage

4. Ask Claude

You never pass a workspace id - a scoped key resolves it. Just say things like:

Plan -> Build (new project)

Plan it in PugBase with the AI planner, then in Claude Code say: "Read my plan from PugBase and scaffold the project." Claude calls get_plan_spec, follows the Constraints, and builds it - reporting progress back as it goes.

Team plans - build features in parallel

A plan's Tasks are split per FEATURE (e.g. Authentication, Dashboard), each with its own Frontend / Backend / QA notes plus one final Integration QA note. On the Status page you assign each feature (or one note of it) to a member; every member connects their OWN API key, so several people point their own agents (Claude Code, Cursor) at the same plan and build different features at the same time.

Agents stay in their lane: the plan ships each note's assignee, an agent's first tick on an unassigned note claims it for its member, and ticking someone else's note returns a warning. The Status page shows whose agent is working on what, live. Working solo? Just say "build all features in build order" - one agent works through the whole plan.

How to run it like a real team: the plan's Overview ends with a "Features & build order" table - start with the foundation feature (ONE person or agent builds the app shell, base schema, and skeleton first), then parallelize the features whose dependencies are done. Keep coupled features with the same owner or in sequence. Need to change an API another feature owns? Edit the API Contract note first (comment / mention the owner), then both sides implement the new contract - never patch someone else's endpoints silently. Git stays git: feature branches and small PRs as usual.

Document an existing project

No plan needed. Point Claude Code at your repo and ask it to analyse and document into PugBase - architecture, module map, conventions, with diagrams:

Analyse this codebase and create documentation in PugBase under an "Architecture" session: an overview, an architecture diagram (mermaid), a module map, and key patterns. Use a separate note per topic.

Full project documentation (for developers)

Want complete docs - data dictionary, API reference, flows, gotchas - so anyone (a new teammate, future you, or whoever picks it up) can understand the project? Ask Claude to read the actual source (not a summary) and write an organised doc set into folders. Paste this prompt:

Analyse this codebase and write a COMPLETE documentation set into PugBase, in a "Project Docs" session, organised into folders. READ THE ACTUAL SOURCE FILES (types, components, API routes, config, schema/rules, package.json) - do not summarise from memory. Use create_note with the folder argument, one note per topic, and mermaid for diagrams. Cover every area below that applies to the project:

Architecture/
- Overview: what it does, tech stack, current status
- System diagram (mermaid): how the pieces connect
- Critical flows: the main journeys, step by step

Frontend/
- Routing and pages
- Component map: the key components and what each does
- State management: each store / context and what it holds
- Styling, theming, i18n

Backend & Data/
- Data dictionary: every table/collection and field (name, type, meaning, constraints), relationships, indexes
- Security and permissions model
- API reference: every endpoint - method, path, auth, request, response, errors

Integrations/
- One note per EXTERNAL service the app connects to (auth, database, payments, AI, email, storage, queues, analytics...): what it is used for, where it is configured, which env vars / keys

Features/
- One note per major feature: what it does and where it lives in the code

Guides/
- Getting started: env vars, run locally, deploy
- Conventions and how to add a feature
- Gotchas / things that bite
- Testing and CI

Keep each note focused. The goal: anyone can understand the project from these notes alone.

User guide (with screenshots)

Want a manual for the people who USE the app, not build it? Claude can write a friendly, step-by-step user guide and capture real UI screenshots with Playwright, embedding them next to each step. Paste this prompt:

Write an END-USER guide for this app into PugBase, in a "User Guide" session, organised into folders. This is for NON-technical users: explain what they SEE and DO, not the code. One note per feature or screen:

- Overview: what the app is, who it is for, and what you can do with it
- For each main feature / menu: what it does, a step-by-step "how to use it", and what you put in vs what you get out (input -> output)

Embed REAL UI screenshots. Drive the app with Playwright (navigate to each screen, call page.screenshot()), then upload each via upload_image and place ![caption](url) next to the step it illustrates.
- Public screens (landing / login / shared pages) can be captured directly.
- For screens behind login, sign in first with a test account (or a saved Playwright storageState) before screenshotting.

Keep it friendly and visual - a brand-new user should be able to follow along.

Test reports

Works with any framework - Claude runs the tests and formats the report. Playwright, Cypress, Jest, Vitest, pytest, go test, cargo test... Failure screenshots go inline via upload_image; a self-contained HTML report (e.g. a coverage report) embeds interactively via upload_file.

5. How Claude reports back

When Claude finishes a task it writes a report into PugBase. Two ways, and the choice matters:

• Native markdown (default). Headings, pass/fail tables, findings, and screenshots embedded inline. It is readable and your team can comment on each block.
• Interactive embed. A self-contained HTML report / trace / chart rendered in a sandboxed iframe. Use it only for genuinely interactive extras - comments do not work inside an embed, so keep the discussion-worthy content native.