init

Init — learn this project, draft conventions.md + project-map.md

Your job is to produce TWO files at the project root for /dev-workflow:feature to rely on. They split by kind of knowledge, and the split is what keeps the workflow affordable:

When you learn something, ask which it is: a rule to follow goes in conventions.md, a location or a capability that already exists goes in project-map.md. Never put the module table or the feature list in conventions.md — it is re-read on every phase by every agent, and that is what the lean budget is protecting.

Steps

1. Inspect the project (read-only first):
   • Detect the tech stack from manifests (package.json, go.mod, pyproject.toml/requirements.txt, Cargo.toml, pom.xml, Gemfile, etc.), framework imports, and the directory layout.
   • Infer the DOMAIN from names, models/entities, routes, and any existing docs (README, docs/). Examples: fintech, healthcare, e-commerce, dev tooling.
   • Note existing coding conventions and architecture/module boundaries. In particular, detect the linter/formatter and record the EXACT command to run them (e.g. ruff check, npm run lint, gofmt -l, cargo fmt) plus the test command, and any naming/error-handling patterns the code already follows. These are what the coder runs and the reviewer enforces.
   • Detect the testing setup, including what is installed but unused. The runner and its exact command; how existing tests build a subject (a testing module, a factory, positional constructor calls); and — the part that gets missed — whether a harness for proving store/external behaviour FOR REAL is already a dependency (an in-memory server such as mongodb-memory-server, Testcontainers, a fixture DB, a fake HTTP server). Grep the manifest, not just the test files: these are routinely installed and then used in one file out of fifty, and an agent that cannot see the harness mocks the database instead and writes a test that cannot fail. Record it by name in conventions.md even when nothing currently uses it. If there is none, say that too — "no real-store harness; add one before claiming store behaviour in a test" is a useful line.
   • Survey what the project already DOES, not just how it is written — this is the part agents are missing today, and it is why they propose rebuilding something that exists. Enumerate the capabilities from the surfaces that declare them: routes/endpoints, CLI commands, event/queue handlers, scheduled jobs, exported modules, UI screens, public API. For each, note what it does and the file that owns it. Then find the SHARED building blocks a new feature is expected to reuse (base classes, middleware, validators, error types, HTTP/DB clients, auth helpers, config access, test fixtures) and the EXTENSION POINTS ("to add a route, touch X"; "migrations live in Y").
   • If a CLAUDE.md already exists, read it and reuse its content — do not duplicate or overwrite it; complement it.
2. Draft conventions.md using the section structure from the plugin template (Domain / Tech stack / Architecture / Coding conventions / Testing / Testing contract / Simplicity contract / Domain-specific correctness rules / Security focus / Workflow files). Fill each section from what you observed; mark anything uncertain as an assumption. Copy the Simplicity contract and Testing contract sections verbatim from the template in BOTH paths (observed project conventions and greenfield default) — they are standing constraints, not fallback baselines. Never rephrase, soften, or drop them.
3. Draft project-map.md using the plugin template's sections (Module map / Existing features / Shared building blocks / Extension points / Known gotchas / Glossary). Fill it from the survey in step 1.
   • Entries are POINTERS: path, what it owns, entry point. Do not restate what the code says or paste signatures — one to three lines per entry.
   • Only write what you actually verified by reading the code. An invented or guessed entry is worse than a missing one, because agents trust this file and will build against it. Mark anything inferred as an assumption for the user to confirm.
   • For Existing features, leave the Shipped column blank for pre-existing work you can't date — the feature workflow fills it for features it ships.
   • If the project is small enough that the map would just re-list five files, say so and keep it to the Module map + Extension points; don't pad it.
4. CHECKPOINT: show BOTH drafts to the user and ask them to confirm or correct them before writing. Call out your assumptions explicitly — the map is the thing later agents will treat as fact. Only write the files after they approve.
5. Make both files visible to ordinary chat, not just this plugin. The plugin's own skills and subagents Read them directly, but a plain Claude Code session only auto-loads CLAUDE.md and the files it @-imports — so without a line in CLAUDE.md, everything you wrote is invisible outside /dev-workflow:*. The two files get DIFFERENT treatment, and the difference is deliberate: